1 DTM Digital Test Manager is a tool that automates the process of software testing. It organizes software tests and automates how you run tests and evaluate their results. 2 @file-specification Executes Digital Test Manager commands contained in the specified file. Format @file-specification 3 Example DTM> @MAIL_TEST %DTM-S-LIBIS, Digital Test Manager library is DUA0:[USER01.DTMLIB] %DTM-S-RESUBMITTED, collection MAIL_TEST has been resubmitted -DTM-I-TEXT, Job MAIL_TEST (queue SYS$BATCH, entry 18) started on SYS$BATCH DTM> This example executes the command procedure MAIL_TEST.COM containing the commands SET LIBRARY DUA0:[USER01.DTMLIB] and SUBMIT MAIL_TEST. 2 ATTACH Switches control from your current process to another process in your job. Format ATTACH [process-name] [/qualifier] 3 Command_Qualifiers /IDENTIFICATION /IDENTIFICATION=pid Specifies the process identification (PID) of the process to which you want to attach your terminal. You can omit the leading zeros when you specify a PID. If you specify the /IDENTIFICATION qualifier, do not specify the process name parameter or the /PARENT qualifier. If you do not specify a qualifier, you must specify a process name. /PARENT Specifies that the process you want to attach to is your original (parent) process. If you specify the /PARENT qualifier, do not specify the process name parameter or the /IDENTIFICATION qualifier. If you do not specify a qualifier, you must specify a process name. 3 Example MAIL> SPAWN DTM . . . DTM> ATTACH/PARENT You have 0 new messages. MAIL> This example uses the OpenVMS Mail Utility (MAIL) command SPAWN to create a subprocess running Digital Test Manager. The Digital Test Manager ATTACH command is then used to attach the terminal back to the MAIL session, the parent process. 2 COMPARE Compares the result file produced for each test description in a collection with its corresponding benchmark file. Format COMPARE collection-name [/qualifier...] 3 Command_Qualifiers /CHARACTERS Performs a character-by-character comparison of the results file with the benchmark file. The default is /SCREENS for interactive tests and /RECORDS for noninteractive tests. /FULL For noninteractive and interactive terminal tests, the /FULL qualifier includes a complete listing of the text in the difference file that was identical and a listing of the differences encountered when the result file and benchmark file are compared. /IGNORE /IGNORE=keyword The /IGNORE qualifier enables you to specify that various aspects of benchmark and result files are to be ignored during comparison. The following keywords apply to noninteractive and interactive terminal tests, only. Keyword Result CASE Ignores any differences between the case of alphabetic characters (A,a,B,b, .. . ) FORM-FEEDS Ignores form-feed characters LEADING_BLANKS Ignores leading blanks and tabs SPACING Treats multiple blanks and tabs as a single space TRAILING_BLANKS Ignores trailing blanks and tabs For interactive terminal tests, if you specify the /IGNORE and /SCREENS qualifiers together, Digital Test Manager performs the comparison screen by screen and ignores the /IGNORE qualifier. If you specify more than one keyword, separate the keywords with commas and enclose the list in parentheses. The output file (your result file) is not changed in any way by the /IGNORE qualifier. The following keyword applies to DECwindows tests only. Keyword Result MASK Ignores masked areas defined on DECwindows benchmark images /LOG /LOG (D) /NOLOG Controls whether Digital Test Manager displays informational and success messages on your screen. /MASK /MASK=(keyword,...) The /MASK qualifier selects one or more sets of mask patterns that will cause certain run-time data to be ignored during the comparison of screens for interactive terminal tests. Such run-time data is ignored by substituting blank space for patterns in both the benchmark and result screens before they are compared. The valid values for keyword are as follows: Keyword Mask ALL Specifies that all the masks in this table be used DATE The date mask ignores comparison of date stamps The following list shows some examples of the date patterns to be ignored; this list is not all inclusive. dd-mmm-yyyy ( example: 17-OCT-1998 ) dd mmm yy ( example: 17 OCT 98 ) yy.mmm.dd ( example: 98.OCT.17 ) mm/dd/yy ( example: 10/17/98 ) yyyy/mm/dd ( example: 1998/10/17 ) month day, year ( example: October 17, 1998 ) month day, year ( example: Oct. 17, 1998 ) day.month.year ( example: 17.October.1998 ) year-month-day ( example: 98-October-17 ) TIME Ignores time stamps with the following forms: hh:mm:ss.xxxx ( example: 15:37:53.22 ) hh:mm:ss ( example: 15:37:53 ) hh:mm ( example: 15:37 ) hh:mm xm ( example: 3:37 PM ) hhHmmm ( example: 15H37m ) hhHmm' ( example: 15H37' ) hh.mm h ( example: 15.37 h ) hh h mm"ss s ( example: 15 h 37"53 s ) hh h mm min ( example: 15 h 37 min ) kl hh.mm ( example: kl 15.37 ) h hh.mm ( example: h 15.37 ) VERSION Ignores file versions on file names FILE_NAMES Ignores file names of the form FILENAME.EXT DIRECTORIES Ignores directory specification fields of the form DISK:[DIRECTORY] If you specify more than one keyword, separate the keywords with commas and enclose the list in parentheses. If you specify only one keyword, omit the parentheses. Masking of is performed in the order of the keywords shown above. /PARALLEL /PARALLEL /NOPARALLEL (D) Specifies whether the lines that do not match in the result and benchmark files are formatted side by side. If you specify the /[NO]PARALLEL and /SCREENS qualifiers together, Digital Test Manager performs the comparison screen by screen and ignores the /[NO]PARALLEL qualifier. /RECORDS For noninteractive and interactive terminal tests, the /RECORDS qualifier performs a record-by-record comparison of the result and benchmark files. The default is /SCREENS for interactive tests and /RECORDS for noninteractive tests. Records are identical only if they contain the same characters. Use this type of comparison only when you expect the record in which a string appears to be the same each time a comparison is performed. Use caution when specifying the /RECORDS qualifier for an interactive test because the records in the result file are not guaranteed to be written the same way each time the test runs. You might want to use the /RECORDS qualifier for an interactive test whose result file is not generated by Digital Test Manager, for example, if you rename a test output file to be DTM$RESULT. /SCREENS Performs a screen-by-screen comparison of the result and benchmark files for an interactive test. The default is /SCREENS for interactive tests and /RECORDS for noninteractive tests. /SENTINEL /SENTINEL=("begin-delimiter","end-delimiter") Specifies a pair of strings used to delimit a section of text to be ignored during the comparison of result and benchmark files for noninteractive tests. The delimiters can be up to 256 characters per line, and must be unique. Any text between and including the delimiters is treated as if it did not exist. If you do not enclose the sentinel strings in quotation marks, they are converted to uppercase before the comparison of the files. Sentinel strings may contain any characters, but if you include spaces, tabs or commas, they must be enclosed in quotation marks. /WIDTH /WIDTH=n For noninteractive and interactive terminal tests that were compared with the /CHARACTERS or /RECORDS qualifier, the /WIDTH qualifier specifies the maximum width allowed for the differences report. The minimum width is 48 columns and the maximum width is 511 columns. The default value is 132 columns. 3 Example DTM> COMPARE MAIL_COLL %DTM-I-SUCCEEDED, the comparison for the test MAIL_TEST succeeded %DTM-I-SUCCEEDED, the comparison for the test SEND_MAIL_TEST succeeded %DTM-S-COMPARED, collection MAIL_COLL compared DTM> This example compares the results for all tests in the collection MAIL_COLL. For each test, Digital Test Manager deletes the result files for tests whose benchmark and result files match, and it creates a difference file for tests whose benchmark and result files differ. 2 COPY 3 TEST_DESCRIPTION Copies an existing test description. Format COPY TEST_DESCRIPTION test-name1 test-name2 [/qualifier...] "remark" 4 Restrictions o The /COMMAND qualifier applies to DECwindows tests only. o The /NOFILTERS qualifier applies to interactive and noninteractive terminal tests only. 4 Command_Qualifiers /COMMAND /COMMAND=command By default, the new test description has the same command as the copied test description. If you specify the /COMMAND qualifier, you associate a new command with the new test description. If you specify the /NOCOMMAND qualifier, the associated command is not copied with the test description. The qualifier applies to DECwindows tests only. /COMPARISON_TYPE /COMPARISON_TYPE=keyword Specifies how the result and benchmark files are to be compared. A comparison type is not associated with the test description. The valid values for keyword are as follows: Keyword Meaning CHARACTERS Compares files character by character. RECORDS Compares files record by record. This is the default for noninteractive terminal tests. SCREENS Compares files screen by screen; screens not marked are not compared. This is the default for interactive terminal and DECwindows tests. DECwindows tests can only use the SCREENS comparison type. The SCREENS comparison type is also the default comparison type for interactive terminal tests. If you specify the /COMPARISON_ TYPE=SCREENS qualifier for a noninteractive test, this value is ignored. /EPILOGUE /EPILOGUE=file-specification /NOEPILOGUE Determines whether a test epilogue file is associated with the test description. The epilogue file associated with the existing test description is also associated with the new test description. The /EPILOGUE qualifier causes the specified epilogue file to replace the existing epilogue file. The /NOEPILOGUE qualifier specifies that no epilogue file be associated with the new test description. /NOFILTERS Specifies that no filters be associated with the new test description. By default, the filters associated with the existing interactive or noninteractive terminal test descriptions are also associated with the new test descriptions. /NOGROUPS Specifies that the new test description does not belong to any groups. If you do not specify this qualifier, the new test description belongs to the same group (or groups) as the previous test description. /LOG /LOG (D) /NOLOG Controls whether Digital Test Manager displays informational and success messages on your screen. /PROLOGUE /PROLOGUE=file-specification /NOPROLOGUE Determines whether a test prologue file is associated with the test description. The prologue file associated with the existing test description is also associated with the new test description. The /PROLOGUE qualifier causes the specified prologue file to replace the existing prologue file. The /NOPROLOGUE qualifier specifies that no prologue file be associated with the new test description. /REMARK /REMARK="string" /NOREMARK Determines whether a remark is associated with the new test description. By default, the remark associated with the new test description will be a copy of the remark associated with the existing test description. This remark is associated with the test description you are creating; it is not the remark logged with the COPY TEST_DESCRIPTION command. The /REMARK qualifier replaces the remark currently associated with the test description with the remark you specify. The /NOREMARK qualifier specifies that no remark be associated with the new test description. /TEMPLATE /TEMPLATE=file-specification /NOTEMPLATE If you do not specify this qualifier, the existing template file is copied for the new test. If you specify the /TEMPLATE qualifier, the existing template file is replaced by the specified template file. If you specify the /NOTEMPLATE qualifier, Digital Test Manager creates the template file name in the form test-name.COM for a noninteractive test and test-name.SESSION for an interactive or DECwindows test. /NOVARIABLES Specifies that no variables be associated with the new test description. If you do not specify this qualifier, the variables associated with the old test description are associated with the new test description. 4 Example DTM> COPY TEST_DESCRIPTION MAIL_TEST SHOW_ALL_TEST/PROLOGUE=NEWPRO.COM _Remark:SHOW ALL test with new prologue file %DTM-I-DEFAULTED, benchmark file name defaulted to SHOW_ALL_TEST.BMK %DTM-S-COPIED, test description MAIL_TEST copied -DTM-S-CREATED, test description SHOW_ALL_TEST created DTM> This example creates a copy of the existing test description, MAIL_TEST, and names the copy, SHOW_ALL_TEST. The prologue file named NEWPRO.COM is associated with the new test description. 2 CREATE 3 COLLECTION Designates a set of tests as a collection. Format CREATE COLLECTION collection-name test-group-expression [/qualifier...] "remark" 4 Command_Qualifiers /BENCHMARK_DIRECTORY /BENCHMARK_DIRECTORY=directory-specification /NOBENCHMARK_DIRECTORY Determines whether Digital Test Manager should search the default benchmark directory for benchmark files for the specified collection. If you do not include a directory, Digital Test Manager searches the default benchmark directory for the benchmark file established by the SET BENCHMARK_DIRECTORY command. If you include a directory in the benchmark file specification for a test within the collection, Digital Test Manager searches that directory for the benchmark file and (if found) overrides the default directory. The directory you specify can be either another directory or a CMS library. The /NOBENCHMARK_DIRECTORY qualifier overrides the default benchmark directory for the specified collection. Digital Test Manager searches your default directory for all benchmark files without directory specifications. /CLASS /CLASS=(keyword=class-name,...) Specifies the optional CMS class for benchmark files and template files stored in CMS libraries. The keywords, BENCHMARK and TEMPLATE, designate the name of the specific set of generations of elements. If you do not specify a class and the file is stored in a CMS library, the latest generation on the main line of descent is used. You can specify the same class names for your benchmark and template files. If you specify both keywords, separate them with a comma and enclose the list in parentheses. If you specify only one keyword, omit the parentheses. /COMPARE /COMPARE[=(keyword,...)] /NOCOMPARE Determines whether Digital Test Manager compares the results of each test with its benchmark file (the file that contains expected test results) after the collection is executed. The default is /COMPARE. The /COMPARE qualifier specifies that Digital Test Manager is to compare all tests after the collection is executed. A collection must be compared before it can be reviewed. Any differences between the results for a test and its benchmark file are recorded in a difference file for that test. Tests without benchmarks can be compared, but will be marked with the comparison status of new test. When you review tests, you can have benchmark files generated for them. When you enter the /COMPARE qualifier, the COMPARE command default qualifiers (/SCREENS, /LOG, and /WIDTH=132) are in effect. You can optionally specify any of the following COMPARE command qualifiers as keywords: CHARACTERS FULL IGNORE=keyword [NO]PARALLEL RECORDS SCREENS WIDTH The /COMPARE qualifier keywords have the same effect as the COMPARE command qualifiers. See the COMPARE command qualifiers for a description of the /COMPARE qualifier keywords. If you specify more than one keyword, separate the keywords with commas and enclose the list in parentheses. If you specify only one keyword, you can omit the parentheses. The /NOCOMPARE qualifier prevents the automatic comparison that Digital Test Manager ordinarily performs when the collection is executed. You can use the COMPARE command later to compare test results for collections created with the /NOCOMPARE qualifier. /EPILOGUE /EPILOGUE=file-specification /NOEPILOGUE Determines whether the default collection epilogue is run with this collection. The /EPILOGUE qualifier overrides the default collection epilogue file for this collection. The /NOEPILOGUE qualifier runs a collection without a collection epilogue. This qualifier has no effect on individual test epilogues. /LOG /LOG (D) /NOLOG Controls whether Digital Test Manager displays informational and success messages on your screen. /MASK /MASK=(keyword,...) The /MASK qualifier selects one or more sets of mask patterns that will cause certain run-time data to be ignored during the comparison of screens for interactive terminal tests. Such run-time data is ignored by substituting blank space for patterns in both the benchmark and result screens before they are compared. The valid values for keyword are as follows: Keyword Mask ALL Specifies that all the masks in this table be used DATE The date mask ignores comparison of date stamps The following list shows some examples of the date patterns to be ignored; this list is not all inclusive. dd-mmm-yyyy ( example: 17-OCT-1998 ) dd mmm yy ( example: 17 OCT 98 ) yy.mmm.dd ( example: 98.OCT.17 ) mm/dd/yy ( example: 10/17/98 ) yyyy/mm/dd ( example: 1998/10/17 ) month day, year ( example: October 17, 1998 ) month day, year ( example: Oct. 17, 1998 ) day.month.year ( example: 17.October.1998 ) year-month-day ( example: 98-October-17 ) TIME Ignores time stamps with the following forms: hh:mm:ss.xxxx ( example: 15:37:53.22 ) hh:mm:ss ( example: 15:37:53 ) hh:mm ( example: 15:37 ) hh:mm xm ( example: 3:37 PM ) hhHmmm ( example: 15H37m ) hhHmm' ( example: 15H37' ) hh.mm h ( example: 15.37 h ) hh h mm"ss s ( example: 15 h 37"53 s ) hh h mm min ( example: 15 h 37 min ) kl hh.mm ( example: kl 15.37 ) h hh.mm ( example: h 15.37 ) VERSION Ignores file versions on file names FILE_NAMES Ignores file names of the form FILENAME.EXT DIRECTORIES Ignores directory specification fields of the form DISK:[DIRECTORY] If you specify more than one keyword, separate the keywords with commas and enclose the list in parentheses. If you specify only one keyword, omit the parentheses. Masking of is performed in the order of the keywords shown above. /PROLOGUE /PROLOGUE=file-specification /NOPROLOGUE Determines whether the default collection prologue is run with this collection. The /PROLOGUE qualifier overrides the default collection prologue file for this collection. The /NOPROLOGUE qualifier runs a collection without a collection prologue file. This qualifier has no effect on individual test prologues. /REALTIME /REALTIME /NOREALTIME (D) Specifies that the speed of session file playback for all interactive terminal tests in the collection is to be based solely on the speed at which they were recorded and not on the rate at which the applications being tested request input. This qualifier is useful for testing applications that request input before completing processing and display of data. /SENTINEL /SENTINEL=("begin-delimiter","end-delimiter") Specifies a pair of strings used to delimit a section of text to be ignored during the comparison of result and benchmark files for a noninteractive test. The delimiters can be up to 256 characters per line, and must be unique. Any text between and including the delimiters is treated as if it did not exist. If you do not enclose the sentinel strings in quotation marks, they are converted to uppercase before the comparison of the files. Sentinel strings may contain any characters, but if you include spaces, tabs, or commas they must be enclosed in quotation marks. /SUBMIT /SUBMIT[=(keyword,...)] /NOSUBMIT (D) Determines whether the collection is executed immediately after it is created. You can submit collections that contain DECwindows tests but Digital Test Manager must be connected to a DECwindows server for the tests to execute. The /SUBMIT qualifier executes the collection in batch mode immediately after the collection is created. When you enter the /SUBMIT qualifier, the SUBMIT command qualifiers (/KEEP and /LOG) are in effect. You can optionally specify any of the following SUBMIT command qualifiers as keywords: AFTER [NO]CHARACTERISTICS CPUTIME [NO]HOLD [NO]KEEP [NO]LOG_FILE NAME [NO]NOTIFY [NO]PRINTER PRIORITY QUEUE [NO]USER WSDEFAULT WSEXTENT WSQUOTA If you specify more than one keyword, separate the keywords with commas and enclose the list in parentheses. If you specify only one keyword, you can omit the parentheses. The /NOSUBMIT qualifier creates the collection without submitting it to the batch queue. To run the collection, use the SUBMIT command. /TEMPLATE_DIRECTORY /TEMPLATE_DIRECTORY=directory-specification /NOTEMPLATE_DIRECTORY Determines whether Digital Test Manager should search the default template directory for template files for the specified collection. If you do not include a directory, Digital Test Manager searches the default template directory for the template file established by the SET TEMPLATE_DIRECTORY command. If you include a directory in the template file specification for a test within the collection, Digital Test Manager searches that directory for the template file. The directory you specify can be either another directory or a CMS library. The /NOTEMPLATE_DIRECTORY qualifier overrides the default template directory for the specified collection. Digital Test Manager searches your default directory for all template files without directory specifications. /VARIABLE /VARIABLE=(variable-name=variable-value,...) Overrides the values of the specified global variables for this collection. If you override the value for more than one variable, separate the variables with commas and enclose the list in parentheses. If you override only one variable, omit the parentheses. /VERIFY /VERIFY (D) /NOVERIFY Specifies whether Digital Test Manager is to verify the existence of files associated with all test descriptions before creating the collection. If a referenced file does not exist, Digital Test Manager does not create the collection. The /NOVERIFY qualifier causes Digital Test Manager to create the collection without verifying the existence of files associated with all test descriptions before creating the collection. If a file associated with a test description is missing when a collection executes, Digital Test Manager may not run that test. 4 Parameter_Qualifiers /GROUP Identifies the immediately preceding item in the test group expression as a group. If a test group expression is a list, use this qualifier after each item in the list that designates a group. The default is /TEST_DESCRIPTION. /TEST_DESCRIPTION Identifies the immediately preceding item in the test group expression as a test expression. This is the default. 4 Examples 1. DTM> CREATE COLLECTION MAIL_COLL MAIL*/NOPROLOGUE _Remark: Tests of MAIL commands %DTM-S-CREATED, collection MAIL_COLL created DTM> This example creates the collection MAIL_COLL. It uses a qualifier to specify that there is to be no collection prologue file associated with this collection, and uses wildcards to specify which tests go into the collection. 2. DTM> CREATE COLLECTION MAIL_PLUS MAIL*, - _DTM> SEND_NONINT/GROUP _Remark: More MAIL tests %DTM-S-CREATED, collection MAIL_PLUS created DTM> This example creates the collection MAIL_PLUS. The test group expression specifies all tests that begin with MAIL, and all tests in the group SEND_NONINT at the time the collection is created. 3 GROUP Creates a group in the Digital Test Manager library. Format CREATE GROUP group-name [/qualifier] "remark" 4 Command_Qualifier /LOG /LOG (D) /NOLOG Controls whether Digital Test Manager displays informational and success messages on your screen. 4 Example DTM> CREATE GROUP SEND_NONINT _Remark: Tests of MAIL commands that send text (SEND, REPLY, etc.) %DTM-S-CREATED, group SEND_NONINT created DTM> This example creates the group SEND_NONINT. 3 LIBRARY Creates a Digital Test Manager library in an empty OpenVMS directory. Format CREATE LIBRARY directory-specification [/qualifier] "remark" 4 Restrictions o Do not create subdirectories of the directory containing the Digital Test Manager library. Digital Test Manager recognizes that they are not part of the library and may delete them. o Do not create or modify files in the Digital Test Manager library and do not delete files from the Digital Test Manager library. o Do not access the Digital Test Manager library with commands other than Digital Test Manager commands. Use only Digital Test Manager Review subsystem commands to access test run output files. 4 Command_Qualifier /LOG /LOG (D) /NOLOG Controls whether Digital Test Manager displays informational and success messages on your screen. 4 Example $ CREATE/DIR [USER01.DTMLIB] $ DTM DTM> CREATE LIBRARY [USER01.DTMLIB] %DTM-S-CREATED, Digital Test Manager library DUA0:[USER01.DTMLIB] created DTM> This example shows how to create a Digital Test Manager library by first creating an empty directory, DTMLIB.DIR, and then using the CREATE LIBRARY command to turn this directory into a Digital Test Manager library. 3 TEST_DESCRIPTION Creates a test description in the Digital Test Manager library. Format CREATE TEST_DESCRIPTION test-name [/qualifier...] "remark" 4 Restrictions o The /COMMAND qualifier applies to DECwindows tests only. o The /FILTER qualifier applies to noninteractive and terminal tests only. 4 Command_Qualifiers /BENCHMARK /BENCHMARK=file-specification Specifies the file to contain the expected output from the test's execution. Digital Test Manager supplies a file name of the form test-name.BMK. If your file specification includes a directory specification, it overrides the default benchmark directory for the library. Benchmark files may be located in the Digital Test Manager library, in another directory, or in a CMS library. /COMMAND /COMMAND="DCL-command" Specifies a command to be executed before the test is recorded or executed. Use this qualifier to start applications for inclusion in the test. This qualifier applies to DECwindows tests only. /COMPARISON_TYPE /COMPARISON_TYPE=keyword Specifies how the result and benchmark files are to be compared. A comparison type is not associated with the test description. The valid values for keyword are as follows: Keyword Meaning CHARACTERS Compares files character by character. RECORDS Compares files record by record. This is the default for noninteractive terminal tests. SCREENS Compares files screen by screen; screens not marked are not compared. This is the default for interactive terminal and DECwindows tests. DECwindows tests can only use the SCREENS comparison type. The SCREENS comparison type is also the default comparison type for interactive terminal tests. If you specify the /COMPARISON_TYPE=SCREENS qualifier for a noninteractive test, this value is ignored. /DECWINDOWS Specifies that the test being created is marked as a DECwindows test. /EPILOGUE /EPILOGUE=file-specification Adds the specified epilogue file to the test description. The test epilogue file is run immediately after the test template file is executed. This epilogue file is unrelated to the collection epilogue file. You cannot store epilogue files in the Digital Test Manager library; store them in another directory or in a CMS library. /FILTER /FILTER=(keyword,...) Available for interactive and noninteractive terminal tests only, the /FILTER qualifier selects one or more filters to remove run-time data from the result file that the test run produces. The valid values for keyword are as follows: Keyword Filter ALL Specifies that all the filters in this table be used DATE Where the date form is abbreviated, the date filter replaces date stamps by substituting a "d" for each displayed number of the day of the month, an "m" for each displayed letter of the month, and a "y" for each displayed number of the year. Where the date form is spelled out, the month name is replaced by "month", the numeric day is replaced by "day", and the year is replaced by "year". The following list shows some examples of the date filtering functions; this list is not all inclusive. 17-OCT-1998 with dd-mmm-yyyy 17 OCT 98 with dd mmm yy 98.OCT.17 with yy.mmm.dd 10/17/98 with mm/dd/yy 1998/10/17 with yyyy/mm/dd October 17, 1998 with month day, year Oct. 17, 1998 with month day, year 17.October.1998 with day.month.year 98-October-17 with year-month-day TIME Replaces time stamps with the following forms: 15:37:53.22 with hh:mm:ss.xxxx 15:37:53 with hh:mm:ss 15:37 with hh:mm 3:37 PM with hh:mm xm 15H37m with hhHmmm 15H37' with hhHmm' 15.37 h with hh.mm h 15 h 37"53 s with hh h mm"ss s 15 h 37 min with hh h mm min kl 15.37 with kl hh.mm h 15.37 with h hh.mm FILE_NAMES Replaces the file names with FILENAME.EXT DIRECTORIES Replaces the directory specification field in the file specification with DISK:[DIRECTORY] TRACE_BACK Replaces 32-bit memory addresses with xxxxxxxx and 64-bit memory addresses with xxxxxxxx xxxxxxxx. VERSION Replaces file versions with VERSION If you specify more than one keyword, separate the keywords with commas and enclose the list in parentheses. If you specify only one keyword, omit the parentheses. /INTERACTIVE /INTERACTIVE /NOINTERACTIVE (D) Specifies whether the test being created is marked as an interactive terminal test. The /INTERACTIVE qualifier marks a test description as containing an interactive terminal test. The /NOINTERACTIVE qualifier marks a test description as containing a noninteractive test. /LOG /LOG (D) /NOLOG Controls whether Digital Test Manager displays informational and success messages on your screen. /PROLOGUE /PROLOGUE=file-specification Adds the specified prologue file to the test description. The test prologue file is run immediately before the test template file is executed. This prologue file is unrelated to the collection prologue file. You cannot store prologue files in the Digital Test Manager library; store them in another directory or in a CMS library. /TEMPLATE /TEMPLATE=file-specification Specifies the command file that runs a test, the file containing an interactive terminal or DECwindows session. Digital Test Manager supplies a template file name of the form test-name.COM for noninteractive tests and test-name.SESSION for interactive and DECwindows tests. If your file specification includes a directory specification, Digital Test Manager ignores the default template directory. You cannot store template files that you create, except SESSION files, in the Digital Test Manager library; store them in another directory, or in a CMS library. /VARIABLE /VARIABLE=(variable-name[=variable-value],...) Enables you to associate existing variables with the test description you are creating. The variables you specify must be defined in the Digital Test Manager library by using the CREATE VARIABLE command. A variable associated with a test description by this qualifier is local in scope. The /VARIABLE qualifier also enables you to redefine values for the variables you specify. If you specify an optional value, the variable takes on that value only for this test description; the value of the original variable is unaffected. If you specify more than one variable name, separate the names with commas and enclose the list in parentheses. If you specify only one variable name, omit the parentheses. You cannot use wildcards. 4 Examples 1. DTM> CREATE TEST_DESCRIPTION SEND_MAIL_TEST _Remark: Send a message test. %DTM-I-DEFAULTED, benchmark file name defaulted to SEND_MAIL_TEST.BMK %DTM-I-DEFAULTED, template file name defaulted to SEND_MAIL_TEST.COM %DTM-S-CREATED, test description SEND_MAIL_TEST created. DTM> This example creates a noninteractive test description with the test name SEND_MAIL_TEST. 2. DTM> CREATE TEST_DESCRIPTION/TEMPLATE=MAIL_INT.COM - _DTM> /INTERACTIVE/PROLOGUE=NOBROADCAST.COM/EPILOGUE=BROADCAST.COM _test name: MAIL_TEST_INT _Remark: Creating a MAIL test %DTM-I-DEFAULTED, benchmark file name defaulted to MAIL_TEST_INT.BMK %DTM-I-DEFAULTED, template file name defaulted to MAIL_TEST_INT.SESSION %DTM-S-CREATED, test description MAIL_TEST_INT created DTM> This example creates an interactive test description MAIL_TEST_INT and includes template, prologue, and epilogue file names. Note that Digital Test Manager prompts for the test name and remark. 3 VARIABLE Defines a variable in the Digital Test Manager library. Format CREATE VARIABLE variable-name variable-value [/qualifier...] "remark" 4 Command_Qualifiers /GLOBAL Defines the variable as being accessible to all tests in all collections. You cannot specify both /LOCAL and /GLOBAL with the same CREATE VARIABLE command. The default is /LOCAL. /LOCAL Defines the variable as being accessible only to an individual test that references it in its test description. The default is /LOCAL. You cannot specify both /LOCAL and /GLOBAL with the same CREATE VARIABLE command. /LOG /LOG (D) /NOLOG Controls whether Digital Test Manager displays informational and success messages on your screen. /LOGICAL Defines the variable as a OpenVMS logical name. You cannot specify both /LOGICAL and /SYMBOL with the same CREATE VARIABLE command. The default is /SYMBOL. /NUMERIC Used only with the /SYMBOL qualifier, the /NUMERIC qualifier defines the symbol type as a numeric value. Use this qualifier to define a quoted symbol value as numeric. You cannot specify both /NUMERIC and /STRING with the same CREATE VARIABLE command. If the variable value is not enclosed in quotation marks (" "), the variable type is defined as a numeric value. /STRING Used with the /SYMBOL qualifier, the /STRING qualifier defines a symbol type as a text string. Use this qualifier to define an unquoted symbol value as a text string. You cannot specify both /NUMERIC and /STRING with the same CREATE VARIABLE command. If the variable value is enclosed in quotation marks (" "), the variable type is defined as a text string. /SYMBOL Defines the variable to be a OpenVMS symbol. When you specify a variable as a symbol with the /SYMBOL qualifier, you must further define it as either a numeric value (with the /NUMERIC qualifier) or a text string (with the /STRING qualifier). You cannot specify both /LOGICAL and /SYMBOL with the same CREATE VARIABLE command. The default is /SYMBOL. 4 Example DTM> CREATE VARIABLE/SYMBOL/LOCAL INPUT_FILE "emptyfil" _Remark: Name of input file, with an empty file as the default %DTM-S-CREATED, symbol variable INPUT_FILE created. DTM> This example creates the variable INPUT_FILE. It is defined as a local symbol, with a default value of emptyfil. The quotation marks indicate that the value is a string. 2 DEFINE Use DEFINE/KEY to define a key to execute a command string. Format DEFINE/KEY key-name "command-string" [/qualifier...] 3 /KEY Use DEFINE/KEY to define a key to execute a command string. Format DEFINE/KEY key-name "command-string" [/qualifier...] 4 Restrictions o Key definitions apply only to terminal environments. o Keys defined with the DEFINE/KEY command at the Digital Test Manager command level can only be used at the Digital Test Manager command level and are not effective during test recording or in the REVIEW subsystem. A separate DEFINE/KEY command may be used within the REVIEW subsystem to define keys within that environment. 4 Command_Qualifiers /ECHO /ECHO (D) /NOECHO Specifies whether the command is displayed on your screen after you press the defined key. You cannot specify both the /NOECHO qualifier and the /NOTERMINATE qualifier. /IF_STATE /IF_STATE=(state-name,...) /NOIF_STATE Specifies a list of states, any one of which must be set to enable the specified key definition. The default is the current state. Digital Test Manager defines the two state names as DTM and GOLD_DTM. The /NOIF_STATE qualifier selects the current state. /LOCK_STATE /LOCK_STATE /NOLOCK_STATE (D) Specifies the state specified with the /SET_STATE qualifier until you use the /SET_STATE qualifier again to change it. /SET_STATE /SET_STATE=state-name /NOSET_STATE Associates a state with the key you are defining. The default is the current state. Digital Test Manager defines the two state names as DTM and GOLD_DTM. You cannot define a key specifying both the /SET_STATE qualifier and the /TERMINATE qualifier. The /NOSET_STATE qualifier selects the current state. /TERMINATE /TERMINATE /NOTERMINATE (D) Determines whether the specified command string executes when you press the defined key. When you use the /NOTERMINATE qualifier, you must press the RETURN key to execute a command. You cannot specify both the /SET_STATE qualifier and the /TERMINATE qualifier or the /NOECHO qualifier with the /NOTERMINATE qualifier. 4 Examples 1. DTM> DEFINE/KEY KP5 "SET LIBRARY DUA0:[USER01.LIB_A]"/TERMINATE DTM> If you subsequently press keypad 5, the following text is displayed: DTM> SET LIBRARY DUA0:[USER01.LIB_A] %DTM-S-LIBIS, Digital Test Manager library is DUA0:[USER01.LIB_A] DTM> 2. DTM> DEFINE/KEY KP5 /IF_STATE=GOLD_DTM - _DTM> "SET LIBRARY DUA0:[USER01.LIB_B]"/TERMINATE DTM> This example defines GOLD keypad 5 to set the default Digital Test Manager library to a different library than the one in the previous example. If you subsequently press GOLD Keypad 5, the following text is displayed: DTM> SET LIBRARY DUA0:[USER01.LIB_B] %DTM-S-LIBIS, Digital Test Manager library is DUA0:[USER01.LIB_B] DTM> 2 DELETE 3 COLLECTION Deletes the specified collection and any associated difference and result files from the Digital Test Manager library. Format DELETE COLLECTION collection-expression [/qualifier...] "remark" 4 Command_Qualifiers /CONFIRM /CONFIRM (D) /NOCONFIRM Controls whether Digital Test Manager prompts you to confirm each deletion. Valid responses are Yes, No, All, or Quit. /LOG /LOG (D) /NOLOG Controls whether Digital Test Manager displays informational and success messages on your screen. The default is /LOG. 4 Examples 1. DTM> DELETE COLLECTION MAIL_COLL "No longer needed" Confirm deletion of collection MAIL_COLL [Y/N] (N): y %DTM-I-DELETED, collection MAIL_COLL deleted %DTM-S-DELETIONS, 1 deletion completed DTM> This example deletes the collection MAIL_COLL. The default /CONFIRM qualifier is in effect. 2. DTM> DELETE COLLECTION *MAIL* "Deleting all MAIL collections" Confirm deletion of collection MAIL_COLL [Y/N] (N): Y %DTM-I-DELETED, collection MAIL_COLL deleted Confirm deletion of collection DELETE_MAIL_COLL [Y/N] (N): Y %DTM-I-DELETED, collection DELETE_MAIL_COLL deleted %DTM-S-DELETIONS, 2 deletions completed DTM> This example deletes all the collections that contain MAIL as part of their name. The default /CONFIRM qualifier is in effect. 3 GROUP Deletes a group from the Digital Test Manager library. Format DELETE GROUP group-expression [/qualifier...] "remark" 4 Restrictions o You cannot delete a group if it contains any test descriptions or other groups, or if it is a subgroup of another group. If any test descriptions or groups are still in the group when you issue the DELETE GROUP command, Digital Test Manager reports that the specified group has not been deleted. 4 Command_Qualifiers /CONFIRM /CONFIRM (D) /NOCONFIRM Controls whether Digital Test Manager prompts you to confirm each deletion. Valid responses are Yes, No, All, or Quit. /LOG /LOG (D) /NOLOG Controls whether Digital Test Manager displays informational and success messages on your screen. 4 Examples 1. DTM> DELETE GROUP MAIL_NONINT/NOCONFIRM "Getting rid of this group" %DTM-S-DELETED, group MAIL_NONINT deleted DTM> This example deletes the group MAIL_NONINT. You are not prompted for confirmation because the /NOCONFIRM qualifier is in effect. 2. DTM> DELETE GROUP * "Deleting all groups" Confirm deletion of group MATH [Y/N] (N): ALL %DTM-I-DELETED, group MATH deleted %DTM-I-DELETED, group RELOP deleted %DTM-I-DELETED, group VARS deleted %DTM-S-DELETIONS, 3 deletions completed DTM> This example deletes all the groups in the library. The default /CONFIRM qualifier is in effect. By typing ALL, you indicate that all groups can be deleted without further requests for confirmation. 3 HISTORY Deletes history information from the history file. Format DELETE HISTORY [/qualifier...] "remark" 4 Command_Qualifiers /BEFORE /BEFORE=time Deletes all history information from the history file dated prior to the specified date. The deleted information is replaced by a single entry stating that history information has been deleted from the history file. If you omit the /BEFORE qualifier, the default is to remove information that was logged prior to the time you enter the command. If you include the /BEFORE qualifier and do not specify a time, the default is TODAY. You can specify the time as an absolute, delta, or combination time value, or as one of the following keywords: TODAY, TOMORROW, or YESTERDAY. Digital Test Manager interprets TOMORROW as the time at which you enter the DELETE HISTORY command. /CONFIRM /CONFIRM (D) /NOCONFIRM Controls whether Digital Test Manager prompts you to confirm each deletion. Valid responses are Yes, No, All, or Quit. /LOG /LOG (D) /NOLOG Controls whether Digital Test Manager displays informational and success messages on your screen. /OUTPUT /OUTPUT[=file-specification] Sends output from the DELETE HISTORY command to the specified file. The output is written to a file called HISTORY.OUT in your current directory if you do not specify the /OUTPUT qualifier. If you specify the file name without the file type, the file type defaults to .LIS. 4 Example DTM> DELETE HISTORY /BEFORE=08-JAN "Deleting old information" Confirm DELETE HISTORY/BEFORE=8-Jan-1998 [Y/N] (N): Y %DTM-S-HISTDEL, 150 history records deleted DTM> This example deletes all history records in the history file recorded before January 8, 1998. The deleted information is replaced with the following record: * 8-JAN-1998 00:00:00 SMITH REMARK "PREVIOUS HISTORY DELETED" 3 TEST_DESCRIPTION Deletes a test description from the Digital Test Manager library. Format DELETE TEST_DESCRIPTION test-expression [/qualifier...] "remark" 4 Restrictions o You cannot delete a test description if it belongs to a group. Use the REMOVE TEST_DESCRIPTION command to remove a test description from a group. Use the SHOW TEST_DESCRIPTION/GROUPS command to display the groups to which the test description belongs. o Do not delete a test description that is part of an existing collection. If you delete a test description that is part of a collection, you may see error messages when you issue other Digital Test Manager commands. For example, if you review a collection from which you have deleted a test description and its associated benchmark file for a noninteractive test, you will see a message indicating that the result description contains errors and you will be unable to examine the benchmark file for this result description. If you delete the test description and benchmark file for an interactive test that uses a screen comparison, you will be unable to examine any of the files associated with the test. 4 Command_Qualifiers /CONFIRM /CONFIRM (D) /NOCONFIRM Controls whether Digital Test Manager prompts you to confirm each deletion. Valid responses are Yes, No, All, or Quit. /LOG /LOG (D) /NOLOG Controls whether Digital Test Manager displays informational and success messages on your screen. 4 Examples 1. DTM> DELETE TEST_DESCRIPTION/NOCONFIRM RMTEST "Deleting RMTEST" %DTM-S-DELETED, test_description RMTEST deleted DTM> This example deletes the test description RMTEST. The /NOCONFIRM qualifier is in effect. 2. DTM> DELETE TEST_DESCRIPTION/NOCONFIRM *TEST* _Remark: Deleting all MAIL tests %DTM-I-DELETED, test_description MAIL_TEST deleted %DTM-I-DELETED, test_description RMTEST deleted %DTM-I-DELETED, test_description SEND_MAIL_TEST deleted %DTM-I-DELETED, test_description TEST_TUBE deleted %DTM-S-DELETIONS, 4 test_descriptions deleted DTM> This example deletes from the current library all the test descriptions that contain TEST as part of their name. The /NOCONFIRM qualifier is in effect. 3 VARIABLE Deletes specified variables from the Digital Test Manager library. Format DELETE VARIABLE variable-expression [/qualifier...] "remark" 4 Restrictions o If you attempt to delete several variables and one or more of them are associated with test descriptions, Digital Test Manager deletes only those variables not associated with a test description. 4 Command_Qualifiers /CONFIRM /CONFIRM (D) /NOCONFIRM Controls whether Digital Test Manager prompts you to confirm each deletion. Valid responses are Yes, No, All, or Quit. /LOG /LOG (D) /NOLOG Controls whether Digital Test Manager displays informational and success messages on your screen. 4 Example DTM> DELETE VARIABLE INPUT_FILE "Deleting variable INPUT_FILE" Confirm deletion of variable INPUT_FILE [Y/N] (N): y %DTM-S-DELETED, variable INPUT_FILE deleted. DTM> This example deletes the variable INPUT_FILE. The default /CONFIRM qualifier is in effect. 2 DISPLAY Displays the benchmark file for a specified interactive terminal test. Format DISPLAY test-name [/qualifier] 3 Command_Qualifier /BENCHMARK Specifies that the benchmark file associated with the specified interactive terminal test is to be displayed. The default is to display the benchmark file. 3 Example DTM> DISPLAY/BENCHMARK MEMO_TEST DTM> This example displays the banner screen, Screen 0, for interactive display. Follow the directions on the screen to display your benchmark file. 2 DTM Invokes the Digital Test Manager. You enter the DTM command at the DCL prompt ($). Format DTM [/qualifier] 3 Command_Qualifier /INIT /INIT (D) /NOINIT Specifies whether Digital Test Manager executes the initialization file (defined by the logical name DTM$INIT) when invoked. The default is to execute any existing initialization file whenever you invoke Digital Test Manager. /INTERFACE /INTERFACE=interface Specifies that Digital Test Manager is to run in the character cell (terminal) or DECwindows environment. The options for this qualifier are CHARACTER_CELL (the default) and DECWINDOWS. 3 Example $ DTM DTM> This example shows how to invoke the Digital Test Manager system. 2 EXIT Terminates a Digital Test Manager session. Format EXIT 3 Example DTM> EXIT $ This example terminates a Digital Test Manager session. 2 EXTRACT Extracts an input file from an interactive terminal or DECwindows session file. Format EXTRACT session-file-specification [input-file-specification] [/qualifier...] 3 Restrictions o The EXTRACT command is used for interactive terminal and DECwindows tests only. o The /TERMINATION_CHARACTER qualifier applies to terminal tests only. 3 Command_Qualifiers /DECWINDOWS Specifies that the session file is a recorded DECwindows session. /INTERACTIVE /INTERACTIVE (D) Specifies that the session file is a recorded terminal session. /LOG /LOG (D) /NOLOG Controls whether Digital Test Manager displays informational and success messages on your screen. /TERMINATION_CHARACTER /TERMINATION_CHARACTER=character Specifies the character that Digital Test Manager interprets as the termination character when you extract the input file from the terminal session file. Digital Test Manager uses this information when translating recording functions in the session file to special strings in the input file. If you used a termination character other than the default termination character CTRL/P when recording the session file, specify that termination character on the EXTRACT command line. The termination character can be any single character, such as an asterisk (*), or a control sequence, such as CTRL/P. To specify a control character, enter a circumflex (^) followed by a letter. For example, to enter the termination character sequence CTRL/D, enter a circumflex followed by a D (/TERMINATION_CHARACTER=^D). You can also specify a termination character by its ASCII decimal representation. For example, you can use the ASCII number 16 to specify CTRL/P. 3 Examples 1. DTM> EXTRACT SAMPLE.SESSION SAMPLE.INP DTM-S-EXTRACTED, input file SAMPLE.INP created DTM> This example creates the terminal input file SAMPLE.INP. You can edit this file and use it in conjunction with the RECORD/INPUT command. 2. DTM> EXTRACT/DECWINDOWS DECW_SAMPLE.SESSION DECW_SAMPLE.INP DTM-S-EXTRACTED, input file SAMPLE.INP created DTM> This example creates the DECwindows input file DECW_SAMPLE.INP. You can edit this file and use it in conjunction with the RECORD/INPUT command. 2 FILTER Replaces run-time-dependent information with constants in a specified file. You can use Digital Test Manager filters on Digital Test Manager files and other ASCII files. Format FILTER file-specification [/qualifier...] 3 Restrictions o The FILTER command is for use with noninteractive and terminal tests only. 3 Command_Qualifiers /ALL Specifies that all the filters be run on the specified file. /DATE Where the date form is abbreviated, the date filter replaces date stamps by substituting a "d" for each displayed number of the day of the month, an "m" for each displayed letter of the month, and a "y" for each displayed number of the year. Where the date form is spelled out, the month name is replaced by "month", the numeric day is replaced by "day", and the year is replaced by "year". The following list shows some examples of the date filtering functions; this list is not all inclusive. 17-OCT-1998 with dd-mmm-yyyy 17 OCT 98 with dd mmm yy 98.OCT.17 with yy.mmm.dd 10/17/98 with mm/dd/yy 1998/10/17 with yyyy/mm/dd October 17, 1998 with month day, year Oct. 17, 1998 with month day, year 17.October.1998 with day.month.year 98-October-17 with year-month-day /DIRECTORIES Replaces the directory specification field in the file specification with DISK:[DIRECTORY]. /FILE_NAMES Replaces the file names with FILENAME.EXT. /LOG /LOG (D) /NOLOG Controls whether Digital Test Manager displays informational and success messages on your screen. /TIME Replaces time stamps with the following forms: 15:37:53.22 with hh:mm:ss.xxxx 15:37:53 with hh:mm:ss 15:37 with hh:mm 3:37 PM with hh:mm xm 15H37m with hhHmmm 15H37' with hhHmm' 15.37 h with hh.mm h 15 h 37"53 s with hh h mm"ss s 15 h 37 min with hh h mm min kl 15.37 with kl hh.mm h 15.37 with h hh.mm /TRACE_BACK Replaces 32-bit memory addresses with xxxxxxxx and 64-bit memory addresses with xxxxxxxx xxxxxxxx. /USER_FILTER /USER_FILTER=filename /USER_FILTER=(filename[,...]) /NOUSER_FILTER (D) The specified files are executed by DEC Text Processing Utility (DECTPU). If more than one file is specified they are executed in the order given. The user filters are applied before any built-in filters that are also specified on the command line. User filter files can be located either in OpenVMS directories or in Code Management System (CMS) libraries. Files may be specified using logical names including logical names that specify search lists. Wildcards cannot be used. For files in CMS libraries, the most recent generation on the main line of descent is used. Before the first file is executed the file to be filtered is read into the DECTPU buffer "filter_buffer". Next, the file specified by the logical name DTM$UFDEFINES is executed. The system logical name DTM$UFDEFINES references the file SYS$LIBRARY:DTM$UFDEFINES.TPU, which contains definitions of a global replace procedure and patterns which can be used in building filters. This logical can be redefined to point to a custom file. Any errors in accessing the user filter files or in executing the DECTPU commands will be reported. However, they will not cause the FILTER command to fail, and any remaining user and built-in filters will be applied. After all the user filters have been applied, the file being filtered will be written out. If any built-in filters are also specified, they are applied to the newly created file, resulting in a second new version. /VERSION Replaces file versions with VERSION. 3 Example DTM> FILTER/ALL DUA0:[USER01.DTMLIB]FILTER.BMK %DTM-S-FILTERED, expression successfully filtered DTM> This example runs the six standard filters on the file FILTER.BMK. 2 HELP Displays help text for Digital Test Manager and Review subsystem commands. Format HELP [topic] 3 Examples 1. DTM> HELP COPY TEST_DESCRIPTION DTM> This example shows how you can access information about the COPY TEST_DESCRIPTION command from the Digital Test Manager system. 2. DTM_REVIEW> HELP SHOW/SUMMARY This example shows how you can access Digital Test Manager help about the SHOW/SUMMARY command from the Digital Test Manager Review subsystem. 2 INSERT 3 GROUP Places one or more groups in one or more other groups. Format INSERT GROUP group-expression1 group-expression2 [/qualifier...] "remark" 4 Restrictions o Digital Test Manager does not insert the same group into another group more than once. If the first group is already a subgroup of the second group, Digital Test Manager informs you that the INSERT operation has already been done. o Digital Test Manager does not create recursive group structures. If group B is a subgroup of group A, then group A cannot be a subgroup of group B. 4 Command_Qualifiers /CONFIRM /CONFIRM /NOCONFIRM (D) Controls whether Digital Test Manager prompts you to confirm each insertion. Valid responses are Yes, No, All, or Quit. /LOG /LOG (D) /NOLOG Controls whether Digital Test Manager displays informational and success messages on your screen. 4 Examples 1. DTM> INSERT GROUP MARGINS BOUNDARIES _Remark: Inserting group MARGINS into group BOUNDARIES %DTM-S-INSERTED, group MARGINS inserted into group BOUNDARIES DTM> This example inserts the MARGINS group into the BOUNDARIES group. 2. DTM> INSERT GROUP RIGHTMARGIN BOUNDARIES,MARGINS _Remark: Inserting RIGHTMARGIN into MARGINS and BOUNDARIES %DTM-I-INSERTED, group RIGHTMARGIN inserted into group MARGINS %DTM-I-INSERTED, group RIGHTMARGIN inserted into group BOUNDARIES %DTM-S-INSERTIONS, 2 insertions completed DTM> This example inserts the RIGHTMARGIN group into both the MARGINS and BOUNDARIES groups. 3 TEST_DESCRIPTION Places one or more test descriptions into one or more groups. Format INSERT TEST_DESCRIPTION test-group-expression group-expression [/qualifier...] "remark" 4 Command_Qualifiers /CONFIRM /CONFIRM /NOCONFIRM (D) Controls whether Digital Test Manager prompts you to confirm each insertion. Valid responses are Yes, No, All, or Quit. /LOG /LOG (D) /NOLOG Controls whether Digital Test Manager displays informational and success messages on your screen. 4 Parameter_Qualifiers /GROUP Identifies the immediately preceding item in a parameter as a group. If the test group expression is a list, use this qualifier after each item that designates a group. The default is /TEST_DESCRIPTION. /TEST_DESCRIPTION Identifies the immediately preceding item in a parameter as a test. This is the default. 4 Example DTM> INSERT TEST_DESCRIPTION MARGINS/GROUP BOUNDARIES _Remark: Inserting tests in MARGINS into BOUNDARIES %DTM-I-INSERTED, test description BOTTOMEDGE inserted into group BOUNDARIES %DTM-I-INSERTED, test description LMARGIN inserted into group BOUNDARIES %DTM-I-INSERTED, test description RMARGIN inserted into group BOUNDARIES %DTM-I-INSERTED, test description TOPEDGE inserted into group BOUNDARIES %DTM-S-INSERTIONS, 4 insertions completed DTM> This example inserts all the test descriptions in the MARGINS group into the BOUNDARIES group. However, the MARGINS group itself is not inserted. 2 MODIFY 3 GROUP Replaces the remark associated with existing groups. Format MODIFY GROUP group-expression [/qualifier...] "remark" 4 Command_Qualifiers /LOG /LOG (D) /NOLOG Controls whether Digital Test Manager displays informational and success messages on your screen. /REMARK /REMARK="string" /NOREMARK Specifies whether to replace or delete the remark associated with the group. This remark is associated with the group you are modifying; it is not the remark logged with the MODIFY GROUP command. The /REMARK qualifier adds the specified remark to the group. This string replaces any previous remark associated with the group. The /NOREMARK qualifier deletes the remark from the group. 4 Example DTM> MODIFY GROUP MARGINS/REMARK="All border tests" _Remark:Replacing remark for group MARGINS %DTM-S-MODIFIED, group MARGINS modified DTM> This example replaces the existing remark associated with the group MARGINS with the remark "All border tests." It also logs the remark "Replacing remark for group MARGINS" with the MODIFY GROUP command in the history file. 3 TEST_DESCRIPTION Changes specified field values in existing test descriptions. Format MODIFY TEST_DESCRIPTION test-group-expression [/qualifier...] "remark" 4 Restrictions o The /COMMAND qualifier applies to DECwindows tests only. o The /FILTER qualifier applies to noninteractive and terminal tests only. 4 Command_Qualifiers /BENCHMARK /BENCHMARK=file-specification /NOBENCHMARK Specifies whether the benchmark file should be replaced or disassociated from a test description. The /BENCHMARK qualifier adds the specified benchmark file specification to the test description. This benchmark file supersedes any benchmark currently associated with the test description. The new file specification cannot contain a directory specification that points to the Digital Test Manager library. However, you can use DTM$LIB without a file name. The new file specification can specify a directory (other than the Digital Test Manager library) or a CMS library. The new file specification overrides any benchmark directory specified with an earlier CREATE TEST_DESCRIPTION command. The new file specification need not specify the same type of directory as the file specification you are overriding. For example, if you have been storing your benchmark files in a CMS library, you can specify a directory that is not a CMS library. If you specify a file name for a benchmark file that does not exist, Digital Test Manager treats the test like a new test when a collection that contains this test executes. When a benchmark file is created, it will have the file name you specify. The /NOBENCHMARK qualifier removes the benchmark file specification from the test description and replaces it with the default, test-name.BMK. /COMMAND /COMMAND="DCL-command" /NOCOMMAND Specifies a new command to be executed before the recording and execution of a DECwindows test begins. If you specify the /NOCOMMAND qualifier, the command is disassociated from the test description. The qualifier applies to DECwindows tests only. /COMPARISON_TYPE /COMPARISON_TYPE=keyword Specifies how the result and benchmark files are to be compared. The valid values for keyword are as follows: Keyword Meaning CHARACTERS Compares files character by character. RECORDS Compares files record by record. This is the default for noninteractive terminal tests. SCREENS Compares files screen by screen; screens not marked are not compared. This is the default for interactive terminal and DECwindows tests. DECwindows tests can only use the SCREENS comparison type. The SCREENS comparison type is also the default comparison type for interactive terminal tests. If you specify the /COMPARISON_TYPE=SCREENS qualifier for a noninteractive test, this value is ignored. The /NOCOMPARISON_TYPE qualifier disassociates any comparison type from the test description. /EPILOGUE /EPILOGUE=file-specification /NOEPILOGUE Specifies whether the test epilogue file should be replaced or disassociated from a test description. The /EPILOGUE qualifier adds the specified test epilogue file specification to the test description. The test epilogue file is run whenever the test description is run; it does not affect any collection epilogue file run with the test. The /NOEPILOGUE qualifier removes the current test epilogue file specification from the test description. /FILTER /FILTER=(keyword,...) /NOFILTER=(keyword,...) Selects one or more filters to remove run-time variables from the result file produced from the collection run. The following table shows the valid values for keywords: Filter type Description ALL Specifies that all the filters in this table be used DATE Where the date form is abbreviated, the date filter replaces date stamps by substituting a "d" for each displayed number of the day of the month, an "m" for each displayed letter of the month, and a "y" for each displayed number of the year. Where the date form is spelled out, the month name is replaced by "month", the numeric day is replaced by "day", and the year is replaced by "year". The following list shows some examples of the date filtering functions; this list is not all inclusive. 17-OCT-1998 with dd-mmm-yyyy 17 OCT 98 with dd mmm yy 98.OCT.17 with yy.mmm.dd 10/17/98 with mm/dd/yy 1998/10/17 with yyyy/mm/dd October 17, 1998 with month day, year Oct. 17, 1998 with month day, year 17.October.1998 with day.month.year 98-October-17 with year-month-day TIME Replaces time stamps with the following forms: 15:37:53.22 with hh:mm:ss.xxxx 15:37:53 with hh:mm:ss 15:37 with hh:mm 3:37 PM with hh:mm xm 15H37m with hhHmmm 15H37' with hhHmm' 15.37 h with hh.mm h 15 h 37"53 s with hh h mm"ss s 15 h 37 min with hh h mm min kl 15.37 with kl hh.mm h 15.37 with h hh.mm FILE_NAMES Replaces the file names with FILENAME.EXT DIRECTORIES Replaces the directory specification field in the file specification with DISK:[DIRECTORY] TRACE_BACK Replaces 32-bit memory addresses with xxxxxxxx and 64-bit memory addresses with xxxxxxxx xxxxxxxx. VERSION Replaces file versions with VERSION If you specify more than one keyword, separate the keywords with commas and enclose the list in parentheses. If you specify only one keyword, omit the parentheses. The /FILTER qualifier associates the specified filters with the test description. The /NOFILTER qualifier removes the specified filters from the test description. Digital Test Manager does not replace the filters associated with the test description. /LOG /LOG (D) /NOLOG Controls whether Digital Test Manager displays informational and success messages on your screen. /PROLOGUE /PROLOGUE=file-specification /NOPROLOGUE Specifies whether the test prologue file should be replaced or disassociated from the test description. The /PROLOGUE qualifier adds the specified test prologue file specification to the test description. The test prologue is run whenever the test description is run and does not affect any collection prologue run with the test. The /NOPROLOGUE qualifier removes the current test prologue file specification from the test description. /REMARK /REMARK="string" /NOREMARK Specifies whether to replace or delete the remark associated with the test description. The /REMARK qualifier associates the specified remark with the test description being modified. This string replaces any previous remark. The remark parameter specifies the remark associated with this MODIFY TEST_DESCRIPTION command and is logged with it in the history file. The /NOREMARK qualifier deletes the remark string from the test description. /TEMPLATE /TEMPLATE=file-specification /NOTEMPLATE Specifies whether to replace or disassociated from the template file. A test description must always have a template file. /VARIABLE /VARIABLE=(variable-name[=variable-value],...) Enables you to associate existing variables with the test description you are modifying. The variables you specify must be defined in the Digital Test Manager library by using the CREATE VARIABLE command. A variable associated with a test description by this qualifier is local in scope. The /VARIABLE qualifier also enables you to redefine values for the variables you specify. If you specify an optional value, the variable takes on that value only for this test description; the value of the original variable is unaffected. If you specify more than one variable name, separate the names with commas and enclose the list in parentheses. If you specify only one variable name, omit the parentheses. You cannot use wildcards. The /NOVARIABLE qualifier disassociates the specified variables from the test description. 4 Parameter_Qualifiers /GROUP Identifies the immediately preceding item in the parameter as a group expression. The default is /TEST_DESCRIPTION. If a test group expression comprises a list, use this qualifier after each item that designates a group. /TEST_DESCRIPTION Identifies the immediately preceding item in the parameter as a test expression. This is the default. 4 Examples 1. DTM> MODIFY TEST_DESCRIPTION RMTEST/BENCHMARK=RMTEST.BMK _Remark: Replacing old benchmark file %DTM-S-MODIFIED, test description RMTEST modified. DTM> This example replaces a benchmark file specification for the test description RMTEST. 2. DTM> MODIFY TEST_DESCRIPTION SEND_MAIL_TEST - _DTM> /NOBENCHMARK/TEMPLATE=NEWSENDTEST.COM _Remark: Replacing template file and removing benchmark file %DTM-S-MODIFIED, test description SEND_MAIL_TEST modified. DTM> This example replaces the template file specification for the test description SEND_MAIL_TEST and removes the existing benchmark file specification. 3 VARIABLE Modifies variable definitions in the Digital Test Manager library. Format MODIFY VARIABLE variable-expression [/qualifier...] "remark" 4 Command_Qualifiers /GLOBAL Makes the variable expression globally accessible. You cannot specify both the /LOCAL and /GLOBAL qualifiers with the same MODIFY VARIABLE command. /LOCAL Makes the variable expression locally accessible. You cannot specify both the /LOCAL and /GLOBAL qualifiers with the same MODIFY VARIABLE command. /LOG /LOG (D) /NOLOG Controls whether Digital Test Manager displays informational and success messages on your screen. /LOGICAL Changes a variable from a OpenVMS symbol to a OpenVMS logical name. You cannot specify both the /LOGICAL and /SYMBOL qualifiers with the same MODIFY VARIABLE command. /NUMERIC Changes a string variable of a symbol to numeric value. You cannot specify the /NUMERIC and /STRING qualifiers with the same MODIFY VARIABLE command. /REMARK /REMARK="string" /NOREMARK Determines whether to replace or remove the existing remark. The /REMARK qualifier replaces any existing remark with the specified remark. The /NOREMARK qualifier removes the remark string from the variable, leaving the remark field value null. /STRING Changes a numeric variable of a symbol to a string. You cannot specify the /NUMERIC and /STRING qualifiers with the same MODIFY VARIABLE command. /SYMBOL Changes a variable from a OpenVMS logical name to a OpenVMS symbol. You must define variables used as symbols as either numeric or string variable types. You cannot specify both the /LOGICAL and /SYMBOL qualifiers with the same MODIFY VARIABLE command. /VALUE /VALUE=value Changes the value of the variable. A value specified with the MODIFY VARIABLE command replaces any previous value for the variable. 4 Example DTM> MODIFY VARIABLE INPUT_FILE/VALUE=INPUT.RNO _Remark: Replacing value of INPUT_FILE with INPUT.RNO %DTM-S-MODIFIED, variable INPUT_FILE modified. DTM> This example assigns a new default value to the variable INPUT_FILE. 2 PLAY Executes the specified session file and displays the output on your screen. Format PLAY file-specification [/qualifier...] 3 Restrictions o You cannot play a DECwindows session file on a terminal screen. o The /KEYSYM qualifier applies to DECwindows tests only. 3 Command_Qualifiers /AUTOSYNCH Specifies that a DECwindows session file is to be played, producing a new session file with text synchronization added. Only text seen during each playback will be used for synchronization purposes. /COMMAND /COMMAND=DCL-command Specifies a command action to be executed before playing a DECwindows session file. /DECWINDOWS Specifies that the session file being played is a DECwindows session file. /DISPLAY /DISPLAY=screen Specifies the display device on which the output is to be displayed. For interactive terminal sessions, the default is SYS$OUTPUT; for DECwindows sessions, the default is the DECwindows server and screen, generally indicated by the DECW$DISPLAY logical name. /INTERACTIVE /INTERACTIVE (D) Specifies that the session file being played is an interactive terminal session file. /KEYSYM Specifies the command key that is used in controlling DECwindows test sessions. The default command key is F9. The command key must be in the DECwindows Latin-1 KEYSYM encodings. Display the file DECW$INCLUDE:KEYSYMDEF.H with the DCL TYPE command to view the list of the Latin-1 KEYSYM keys. For example, to use F7 as the command key, enter the following command: DTM> PLAY test-name/DECWINDOWS/KEYSYM=F7 /LOG /LOG (D) /NOLOG Controls whether Digital Test Manager displays informational and success messages on your screen. /REALTIME /REALTIME /NOREALTIME (D) Specifies that the speed of interactive terminal session file playback is to be based solely on the speed at which it was recorded and not on the rate at which the application being tested requests input. This qualifier is useful for testing applications that request input before completing processing and display of data. /RESULT_FILE /RESULT_FILE=file-specification /NORESULT_FILE (D) Specifies whether a file is to receive a copy of the output. If you specify /RESULT_FILE but do not include a file specification, Digital Test Manager places the results in a file named file-name.RES. If you specify the /NORESULT_FILE qualifier (the default), the session file is played but the output is not saved. 3 Example DTM> PLAY MEMO_TEST.SESSION %DTM-I-BEGIN, your interactive test session is now beginning... . . . %DTM-S-CONCLUDED, your interactive test session has concluded DTM> This examples displays a message stating that your interactive terminal session is beginning, executes the specified session file, and displays a message stating that the execution has ended. 2 RECORD Records an interactive terminal or DECwindows test. Format RECORD test-name [/qualifier...] "remark" 3 Restrictions o The /APPEND qualifier applies to interactive terminal tests only. o The /FILTER qualifier applies to noninteractive and terminal tests only. o The /KEYSYM qualifier applies to DECwindows tests only. o The /POINTER_MOTION qualifier applies to DECwindows tests only. 3 Qualifiers /APPEND Continues recording the specified test after the end of the input file is reached. The /APPEND qualifier applies to interactive terminal tests only. If you specify an input file using the /INPUT qualifier, Digital Test Manager records using input from the input file. When the end of the input file is reached, this qualifier enables you to record further; if you do not specify this qualifier, recording is terminated when the end of the input file is reached. /AUTO_COMPARE /AUTO_COMPARE /NOAUTO_COMPARE The /AUTO_COMPARE and /NOAUTO_COMPARE qualifiers determine whether automatic screen comparison is enabled at the start of your interactive terminal recording session; there is no automatic comparisons for DECwindows tests. By default, automatic screen compare is in effect. The /NOAUTO_COMPARE qualifier disables automatic screen compare. /DISPLAY /DISPLAY=screen Specifies the display device on which the output is to be displayed. For interactive terminal sessions, the default is SYS$OUTPUT; for DECwindows sessions, the default is the DECwindows server and screen, generally indicated by the DECW$DISPLAY logical name. /EPILOGUE /EPILOGUE /NOEPILOGUE (D) Specifies whether Digital Test Manager is to execute the test epilogue file when interactive recording terminates. /FILTERS /FILTERS /NOFILTERS (D) Specifies whether Digital Test Manager is to filter the benchmark file that is produced when interactive recording terminates. When the test is recorded, Digital Test Manager invokes the filters associated with the test. When using this command on a test with associated user filter variables, the /VARIABLES qualifier must also be used to execute those filters. /INPUT /INPUT=file-specification Specifies an input file containing a textual representation of an interactive terminal or DECwindows session file. For interactive terminal tests, you must create the input file by issuing the EXTRACT command on a previously recorded session. You cannot use wildcards in the file specification. /KEYSYM Specifies the command key that is used in controlling DECwindows test sessions. The default command key is F9. The command key must be in the DECwindows Latin-1 KEYSYM encodings. Display the file DECW$INCLUDE:KEYSYMDEF.H with the DCL TYPE command to view the list of the Latin-1 KEYSYM keys. For example, to use F7 as the command key, enter the following command: DTM> RECORD test-name/KEYSYM=F7 /LOG /LOG (D) /NOLOG Controls whether Digital Test Manager displays informational and success messages on your screen. /POINTER_MOTION /POINTER_MOTION /NOPOINTER_MOTION(D) Specifies whether Digital Test Manager records pointer motion for DECwindows tests. /PROLOGUE /PROLOGUE /NOPROLOGUE (D) Specifies whether Digital Test Manager is to execute the test prologue file before interactive recording begins. /REALTIME Instructs Digital Test Manager to record and forward keypresses to the application as they are entered, and not when the application requests them. By default, Digital Test Manager records keypresses and places them into the terminal input buffer for an application when the application reads from the terminal. This qualifier is intended for use in recording tests where an application will not read from the terminal until data appears in its terminal buffer. /TERMINATION_CHARACTER /TERMINATION_CHARACTER=character Specifies a character sequence for interactive terminal sessions that, when pressed twice, terminates the recording of an interactive terminal or DECwindows session. The default termination character is the sequence CTRL/P. When pressed once, CTRL/P temporarily suspends the recording session to introduce a recording function. For example, CTRL/P E (end automatic screen comparison) is the recording function instructing Digital Test Manager to terminate automatic screen comparison and to begin manual screen comparison. The termination character can be any single character, such as an asterisk (*), or a control sequence, such as CTRL/P. To specify a control character, enter a circumflex (^) followed by a letter. For example, to enter the termination character sequence CTRL/D, enter a circumflex followed by a D (/TERMINATION_CHARACTER=^D). You can also specify a termination character by its ASCII decimal representation. For example, you can use ASCII number 16 to specify CTRL/P. On interactive terminal tests, you can also terminate the recording session by entering the DCL LOGOUT command. If you do not want an accounting summary, enter the DCL STOP/IDENTIFICATION=0 command. /VARIABLES /VARIABLES /NOVARIABLES (D) Specifies whether Digital Test Manager is to define symbols and logical names as specified by the variables associated with the test before recording starts. 3 Example DTM> RECORD MAIL_TEST _Remark: Going to Record the MAIL facility %DTM-I-BEGIN, your interactive test session is now beginning... Type CTRL/P twice to terminate the session. $ . . . ^P %DTM-I-BMK_SAVED, benchmark has been saved in file DUA1:[USER01.DTMLIB]MAI L_TEST.BMK;1 %DTM-S-RECORDED, test MAIL_TEST has been successfully recorded in file DUA1:[USER01.DTMLIB]MAIL_TEST.SESSION DTM> This example shows the recording of interactive terminal test MAIL_TEST. 2 RECREATE Re-creates a collection, providing the same attributes that were part of the original collection. Format RECREATE collection-name [/qualifier...] "remark" 3 Command_Qualifiers /CONFIRM /CONFIRM (D) /NOCONFIRM Controls whether Digital Test Manager prompts you to confirm that you want to re-create a collection. Valid responses are Yes, No, All, or Quit. /LOG /LOG (D) /NOLOG Controls whether Digital Test Manager displays informational and success messages on your screen. 3 Example DTM> RECREATE MAIL_COLL "Re-creating Collection MAIL_COLL" Collection MAIL_COLL has not been reviewed, confirm recreation: [Y/N] (N) Y %DTM-S-DELETED, collection MAIL_COLL deleted %DTM-S-CREATED, collection MAIL_COLL created %DTM-S-RECREATED, collection MAIL_COLL has been re-created DTM> This example re-creates collection MAIL_COLL. In this example, Digital Test Manager prompts for confirmation to re-create the collection without first reviewing it. 2 REMARK Places a remark in the Digital Test Manager history file. Format REMARK "remark" [/qualifier] 3 Command_Qualifier /LOG /LOG (D) /NOLOG Controls whether Digital Test Manager displays informational and success messages on your screen. 3 Example DTM> REMARK "Correcting problems created by - _DTM> system crash while collection was running" %DTM-S-REMARK, remark added to history file DTM> This example adds the remark "Correcting problems created by system crash while collection was running." You might enter such a remark into your history file to clarify your reason for entering a VERIFY/RECOVER command to correct problems with the library. 2 REMOVE 3 GROUP Removes one or more groups from one or more other groups. Format REMOVE GROUP group-expression1 group-expression2 [/qualifier...] "remark" 4 Command_Qualifiers /CONFIRM /CONFIRM (D) /NOCONFIRM Controls whether Digital Test Manager prompts you to confirm each removal. Valid responses are Yes, No, All, or Quit. /LOG /LOG (D) /NOLOG Controls whether Digital Test Manager displays informational and success messages on your screen. 4 Examples 1. DTM> REMOVE GROUP LEFTMARGIN MARGINS /NOCONFIRM _Remark: Removing LEFTMARGIN from MARGIN %DTM-S-REMOVED, group LEFTMARGIN removed from group MARGINS DTM> This example removes the LEFTMARGIN group from the MARGINS group. 2. DTM> REMOVE GROUP RIGHTMARGIN MARGINS,BOUNDARIES /CONFIRM _Remark: Removing RIGHTMARGIN from MARGINS and BOUNDARIES Confirm removal of group RIGHTMARGIN from group BOUNDARIES [Y/N] (N) Y %DTM-I-REMOVED, group RIGHTMARGIN removed from group BOUNDARIES Confirm removal of group RIGHTMARGIN from group MARGINS [Y/N] (N) Y %DTM-I-REMOVED, group RIGHTMARGIN removed from group MARGINS %DTM-S-REMOVALS, 2 removals completed DTM> This example removes the RIGHTMARGIN group from the BOUNDARIES group and the MARGINS group and prompts you to confirm each transaction. 3 TEST_DESCRIPTION Removes one or more test descriptions from one or more groups. Format REMOVE TEST_DESCRIPTION test-group-expression group-expression [/qualifier...] "remark" 4 Command_Qualifiers /CONFIRM /CONFIRM (D) /NOCONFIRM Controls whether Digital Test Manager displays each test description name for you to confirm removal of the test description. Valid responses are Yes, No, All, or Quit. /LOG /LOG (D) /NOLOG Controls whether Digital Test Manager displays informational and success messages on your screen. 4 Parameter_Qualifiers /GROUP Identifies the immediately preceding item in the parameter as a group expression. If a test group expression is a list, use this qualifier after each item that designates a group. The default is /TEST_DESCRIPTION. /TEST_DESCRIPTION Identifies the immediately preceding item in the parameter as a test expression. This is the default. 4 Example DTM> REMOVE TEST_DESCRIPTION MARGINS/GROUP BOUNDARIES/NOCONFIRM _Remark: Removing MARGINS tests from BOUNDARIES %DTM-I-REMOVED, test_description BOTTOMEDGE removed from group BOUNDARIES %DTM-I-REMOVED, test_description LEFTMARGIN removed from group BOUNDARIES %DTM-I-REMOVED, test_description RIGHTMARGIN removed from group BOUNDARIES %DTM-I-REMOVED, test_description TOPEDGE removed from group BOUNDARIES %DTM-S-REMOVALS, 4 removals completed DTM> This example removes all the tests in the MARGINS group from the BOUNDARIES group without prompting for confirmation. 2 REVIEW Invokes the Review subsystem to examine and manipulate test results for a collection of tests. Format REVIEW collection-name [/qualifier] ["remark"] 3 Restrictions o You can only review noninteractive and interactive terminal tests in the Review subsystem. DECwindows tests must be reviewed through the Digital Test Manager DECwindows user interface. 3 Qualifiers /READ_ONLY /READ_ONLY /NOREAD_ONLY (D) Determines whether you are a primary or read-only user of the Review subsystem. There can be only one primary reviewer at a time. This reviewer can enter all Review subsystem commands. There can be multiple read-only reviewers who cannot make changes to the result descriptions or to the files they describe. Read-only reviewers cannot enter the INSERT or UPDATE commands. 3 Example DTM> REVIEW MAIL_COLL Collection MAIL_COLL with 7 tests was created on 7-SEP-1998 09:30:28 by the command: CREATE COLLECTION MAIL_COLL MAIL* "Creating the MAIL tests collection" Last Review Status = not previously reviewed Success count = 4 Unsuccessful count = 1 New test count = 2 Updated test count = 0 Comparisons aborted = 0 Test not run count = 0 Result Description MAIL_TEST Comparison Status : Unsuccessful DTM_REVIEW> This example invokes the Review subsystem for the collection MAIL_COLL. 3 Review_Subsystem The Review subsystem enables you to examine and manipulate tests results for the specified collection. The REVIEW command invokes the Review subsystem. The Review subsystem uses the following commands: 4 @file-specification Executes Digital Test Manager Review subsystem commands contained in the specified file. Format @file-specification 5 Restrictions o You can only specify Review subsystem commands with this @file-specification command. 5 Example DTM_REVIEW> @REVIEW_FILE Result Description MAIL_TEST Comparison Status : Unsuccessful Differences File DUA0:[USER01.DTMLIB]MAIL_TEST.DIF For Result Description MAIL_TEST Digital Test Manager COMPARE utility (1) DUA0:[USER01.DTMLIB]MAIL_TEST.BMK (2) DUA0:[USER01.DTMLIB.RUNMAIL]MAIL_TEST.RES . . . This example executes the command procedure REVIEW_FILE, which contains the NEXT/UNSUCCESSFUL and SHOW/DIFFERENCES commands. 4 ATTACH Switches control from the current process to another process in your job. Format ATTACH process-name [/qualifier...] 5 Command_Qualifiers /IDENTIFICATION /IDENTIFICATION=pid Specifies the process identification (PID) of the process to which you want to attach the terminal. You can omit the leading zeros when you specify a PID. If you specify the /IDENTIFICATION qualifier, do not specify the process name parameter or the /PARENT qualifier. If you do not specify a qualifier, you must specify a process name. /PARENT Specifies that the process you want to attach to is the original (parent) process. If you specify the /PARENT qualifier, do not specify the process name parameter or the /IDENTIFICATION qualifier. If you do not specify a qualifier, you must specify a process name. 5 Example MAIL> SPAWN DTM REVIEW Collection name: MAIL_COLL Collection MAIL_COLL with 1 test was created on 29-JUL-85 15:13:54 by the command: CREATE COLLECTION MAIL_COLL MAIL_TEST "Recording MAIL on the terminal" Last review status = not previously reviewed Success count = 0 Unsuccessful count = 1 New test count = 0 Updated test count = 0 Comparisons aborted = 0 Test not run count = 0 Result Description MAIL_TEST Comparison Status : Unsuccessful DTM_REVIEW> ATTACH/PARENT You have 0 new messages. MAIL> This example uses the MAIL SPAWN command to create a subprocess executing a Digital Test Manager Review subsystem to review collection MAIL_COLL. The Review subsystem ATTACH command is then used to attach the terminal back to the mail session, the parent process. 4 BACK Moves you backward through the sequence of result descriptions being reviewed. Format BACK [count] [/qualifier...] 5 Command_Qualifiers /COMPARISON_ABORTED Moves you to the previous result description for a test whose comparison aborted. /NEW Moves you to the previous result description for a new test. /NOT_RUN Moves you to the previous result description for a test that did not run. /SUCCESSFUL Moves you to the previous successfully compared result description. /UNSUCCESSFUL Moves you to the previous unsuccessfully compared result description. /UPDATED Moves you to the previous updated result description. 5 Example DTM_REVIEW> BACK 2 . . . This example displays the result description that is two positions behind the current result description. 4 DEFINE Use DEFINE/KEY to define a key to execute a command string. Format DEFINE/KEY key-name "command-string" [/qualifier...] 5 /KEY Use DEFINE/KEY to define a key to execute a command string. Format DEFINE/KEY key-name "command-string" [/qualifier...] 6 Restrictions o Key definitions apply only to terminal environments. o Keys defined with the DEFINE/KEY command in the REVIEW subsystem can only be used in the REVIEW subsystem. They are not effective during test recording or in the Digital Test Manager subsystem. A separate DEFINE/KEY command may be used within the Digital Test Manager subsystem to define keys within that environment. 6 Command_Qualifiers /ECHO /ECHO (D) /NOECHO Specifies whether the command is displayed on your screen after you press the defined key. You cannot define a key by specifying both /NOECHO and /NOTERMINATE. /IF_STATE /IF_STATE=(state-name,...) /NOIF_STATE Specifies a list of states, any one of which must be set to enable the specified key definition. The default is the current state. Digital Test Manager defines the two states REVIEW and GOLD_REVIEW. The /NOIF_STATE qualifier selects the current state. /LOCK_STATE /LOCK_STATE /NOLOCK_STATE (D) Retains the state specified with the /SET_STATE qualifier until you use the /SET_STATE qualifier again to change it. /SET_STATE /SET_STATE=state-name /NOSET_STATE Associates a state with the key you are defining. The default is the current state. A state name can be any alphanumeric string. Digital Test Manager defines the two states REVIEW and GOLD_REVIEW. You cannot define a key specifying both /SET_STATE and /TERMINATE. The /NOSET_STATE qualifier selects the current state. /TERMINATE /TERMINATE /NOTERMINATE (D) Determines whether the specified command string executes when you press the defined key. When you use /NOTERMINATE, you must press RETURN to execute the command. You cannot define a key specifying both /SET_STATE and /TERMINATE or /NOECHO and /NOTERMINATE. 6 Example DTM_REVIEW> DEFINE/KEY KP1/IF_STATE=REVIEW/TERMINATE- _DTM_REVIEW> "NEXT/SUCCESSFUL" DTM_REVIEW> DEFINE/KEY KP1/IF_STATE=GOLD_REVIEW/TERMINATE- _DTM_REVIEW> "BACK/SUCCESSFUL" DTM_REVIEW> This example defines two keys on the Review subsystem keypad. When you press the keypad 1 key, you move forward to the next result description for a successful test. When you press the GOLD key followed by the keypad 1 key, you move backward to the previous result description for a successful test. 4 EXIT Terminates the Review session and returns control to the previous command level where you invoked the Review subsystem. Format EXIT [/qualifier...] 5 Command_Qualifiers /NOINSERT Specifies that a group is not to be created from tests marked with the INSERT command when you exit the Review subsystem. /NOPRINT Specifies that files marked with the PRINT command are not to be printed when you exit the Review subsystem. 5 Example DTM_REVIEW> EXIT %DTM-S-EXIT, leaving Review subsystem DTM> This example shows how to exit from the Review subsystem. 4 FIRST Moves you to the first result description in the collection you are reviewing. Format FIRST 5 Example DTM_REVIEW> FIRST . . . This example displays the first result description in a collection. 4 HELP Displays help text for Review subsystem commands. Format HELP [topic] 5 Example DTM_REVIEW> HELP DEFINE DTM REVIEW DEFINE Use DEFINE/KEY to define a key to execute a command string. Format: DTM_REVIEW> DEFINE/KEY key-name "command-string" [/qualifier...] Additional information available: Qualifiers /ECHO /NOECHO /IF_STATE=(state-name,...) /NOIF_STATE /LOCK_STATE /NOLOCK_STATE /SET_STATE=state-name /NOSET_STATE /TERMINATE /NOTERMINATE Parameters Command_Description Example DTM REVIEW DEFINE Subtopic? This example shows how to get help for the DEFINE command. 4 INSERT Marks test descriptions for insertion into a group Digital Test Manager creates when you exit from the Review subsystem. Format INSERT [result-description-expression] [/qualifier...] 5 Command_Qualifiers /COMPARISON_ABORTED Marks for inclusion test descriptions for tests whose comparisons aborted. The default is to mark the test description associated with the current result description. /CONFIRM /CONFIRM /NOCONFIRM (D) Controls whether Digital Test Manager prompts you to confirm the processing of each test description marked for insertion. Valid responses are Yes, No, All, or Quit. /NEW Marks for inclusion test descriptions for new tests. The default is to mark the test description associated with the current result description. /NOT_RUN Marks for inclusion test descriptions for tests that did not run. The default is to mark the test description associated with the current result description. /SUCCESSFUL Marks for inclusion test descriptions for tests that compared successfully. The default is to mark the test description associated with the current result description. /UNSUCCESSFUL Marks for inclusion test descriptions for tests that compared unsuccessfully. The default is to mark the test description associated with the current result description. /UPDATED Marks for inclusion test descriptions for tests whose benchmark files have been updated. The default is to mark the test description associated with the current result description. 5 Example DTM_REVIEW> INSERT MAIL_TEST DTM-S-MRKFORINSERT, test_description MAIL_TEST marked for insertion DTM_REVIEW> EXIT DTM-S-CREATED, group RUNMAIL$DTM_1 created DTM-S-EXIT, leaving Review subsystem DTM> This example inserts the MAIL_TEST test into a group that is created upon leaving the Review subsystem. 4 LAST Moves you to the last result description in the collection you are reviewing. Format LAST 5 Example DTM_REVIEW> LAST . . . This example displays the last result description in a collection. 4 NEXT Moves you forward through the sequence of result descriptions being reviewed. Pressing the RETURN key also moves you forward to the next result description. Format NEXT [count] [/qualifier...] 5 Command_Qualifiers /COMPARISON_ABORTED Moves you to the next result description for a test whose comparison aborted. /NEW Moves you to the next result description for a new test. /NOT_RUN Moves you to the next result description for a test that did not run. /SUCCESSFUL Moves you forward to the next successfully compared result description. /UNSUCCESSFUL Moves you forward to the next unsuccessfully compared result description. /UPDATED Moves you forward to the next result description whose benchmark file has been updated. 5 Example DTM_REVIEW> NEXT 2 . . . This example displays the result description that is two positions ahead of the current result description. 4 PCA Invokes the Analyzer of the VAX Performance and Coverage Analyzer (PCA). Format PCA 4 PRINT Selects one or more files for printing. Format PRINT [result-description-expression] [/qualifier...] 5 Command_Qualifiers /BENCHMARK Prints benchmark files from the specified result descriptions. The default is /RESULT. /COMPARISON_ABORTED Prints files from result descriptions for tests whose comparisons aborted. The default is to select files from the test description associated with the current result description. /DIFFERENCES Prints difference files from the specified result descriptions. The default is /RESULT. /LOG /LOG (D) /NOLOG Controls whether Digital Test Manager displays informational and success messages on the screen. /NEW Prints files from result descriptions for new tests. The default is to select files from the test description associated with the current result description. /NOT_RUN Prints files from result descriptions for tests that did not run. When a test does not run, its result description may or may not contain a benchmark file. The default is to select files from the test description associated with the current result description. /NOW Concatenates all files selected for printing on the current PRINT command and immediately places them in the print queue. The default is to place the concatenated files in the print queue when you exit from the Review subsystem. /RESULT Prints the result file from the specified result descriptions. This is the default. /SELECTED Concatenates all files already selected for printing and the currently specified file and immediately places them in the print queue. The default is to place the concatenated files in the print queue when you exit from the Review subsystem. /SUCCESSFUL Prints files from result descriptions for tests that compared successfully. The default is to select files from the test description associated with the current result description. /UNSUCCESSFUL Prints files from result descriptions for tests that compared unsuccessfully. The default is to select files from the test description associated with the current result description. /UPDATED Prints files from result descriptions whose benchmark files have been updated. The default is to select files from the test description associated with the current result description. 5 Example DTM_REVIEW> PRINT/DIFFERENCES %DTM-S-PRINT, file DUA1:[USER01.DTMLIB.MAIL_COLLECTION]MAIL_TEST.DIF of test MAIL_TEST selected for printing DTM_REVIEW> EXIT %DTM-S-PRINTQD, print job has been sent to the print queue -DTM-I-TEXT, Job MAIL_TEST (queue SYS$PRINT, entry 32) started on SYS$PRINT %DTM-S-EXIT, leaving Review subsystem DTM> This example shows how to queue the differences file for printing. 4 SELECT Moves you to the specified result description. Format SELECT result-description-name 5 Example DTM_REVIEW> SELECT MAIL_TEST Result Description MAIL_TEST Comparison Status : Unsuccessful This example displays the MAIL_TEST result description in a collection. 4 SHOW Displays and describes output files for specified result descriptions. Format SHOW [result-description-expression] [/qualifier...] 5 Command_Qualifiers /BENCHMARK Displays the benchmark file. The default is to state whether output files (benchmark, difference, and result files) exist. If the benchmark file exists, its file specification is displayed. For a noninteractive test, Digital Test Manager displays the benchmark file. For an interactive test, Digital Test Manager displays the benchmark file screen by screen and provides you with a keypad for manipulating the file. If the benchmark file is in a CMS library, Digital Test Manager fetches the benchmark. If you include a comparison status qualifier with the /BENCHMARK qualifier, Digital Test Manager displays the benchmark file for result descriptions with the specified comparison status. /COMPARISON_ABORTED States whether output files (benchmark, difference, and result files) exist for the specified result descriptions with the comparison aborted comparison status. The default is to display information for the current result description. If the benchmark file exists, its file specification is displayed. If you include an output file qualifier with the /COMPARISON_ABORTED qualifier, the specified output files are displayed for result descriptions with the comparison aborted comparison status. You cannot specify a comparison status qualifier with a result description name parameter; a result description expression is required. /DIFFERENCES Displays the difference file. The default is to state whether output files (benchmark, difference, and result files) exist. If the benchmark file exists, its file specification is displayed. For a noninteractive test, Digital Test Manager displays the difference file. For an interactive test, Digital Test Manager displays the benchmark and result files screen by screen with differences marked and provides you with a keypad for manipulating the files. If you include a comparison status qualifier with the /DIFFERENCES qualifier, Digital Test Manager displays the difference file for result descriptions with the specified comparison status. /FILES Displays the comparison status for result descriptions and states whether output files (benchmark, difference, and result files) exist for the result description. The default is /FILES. If the benchmark file exists, its file specification is displayed. You cannot include the /FILES qualifier with the included /BENCHMARK, /DIFFERENCES, /RESULT, and /SUMMARY qualifiers. /NEW States whether output files (benchmark, difference, and result files) exist for result descriptions with the new comparison status. The default is to display information for the current result description. If you include an output file qualifier with the /NEW qualifier, the specified output files are displayed for result descriptions with the new comparison status. If a test is new, it has a result file but it does not have a benchmark or difference file. You cannot specify a comparison status qualifier with a result description name parameter; a result description expression is required. /NOT_RUN States whether output files (benchmark, difference, and result files) exist for result descriptions with the not run comparison status. The default is to display information for the current result description. If the benchmark file exists, its file specification is displayed. If you include an output file qualifier with the /NOT_RUN qualifier, the specified output files are displayed for result descriptions with the not run comparison status. If a test does not run, it does not have a result or difference file. It might have a benchmark file. You cannot specify a comparison status qualifier with a result description name parameter. A result description expression is required. /OUTPUT /OUTPUT[=file-specification] Sends the requested output to the specified file. The default is SYS$OUTPUT. /RESULT Displays the result file. The default is to state whether output files (benchmark, difference, and result files) exist. For a noninteractive test, Digital Test Manager displays the result file. If the benchmark file exists, its file specification is displayed. For an interactive test, Digital Test Manager displays the result file screen by screen and provides you with a keypad for manipulating the file. If you include a comparison status qualifier with the /RESULT qualifier, Digital Test Manager displays the result file for result descriptions with the specified comparison status. /SUCCESSFUL States whether output files (benchmark, difference, and result files) exist for result descriptions with the successful comparison status. The default is to display information for the current result description. If the benchmark file exists, its file specification is displayed. If you include an output file qualifier with the /SUCCESSFUL qualifier, the specified output files are displayed for result descriptions with the successful comparison status. If a test is successful, it has a benchmark file. Its result file was deleted and no difference file was created. You cannot specify a comparison status qualifier with a result description name parameter; a result description expression is required. /SUMMARY Displays the Collection Summary Information (the information displayed when you first enter the Review subsystem). The default is /FILES. You cannot specify the /SUMMARY and /FILES qualifiers with the same command. The /SUMMARY qualifier is mutually exclusive with all qualifiers except the /OUTPUT qualifier. /UNSUCCESSFUL States whether output files (benchmark, difference, and result files) exist for result descriptions with the unsuccessful comparison status. The default is to display information for the current result description. If the benchmark file exists, its file specification is displayed. If you include an output file qualifier with the /UNSUCCESSFUL qualifier, the specified output files are displayed for result descriptions with the unsuccessful comparison status. (If a test is unsuccessful, it has benchmark, result, and difference files.) You cannot specify a comparison status qualifier with a result description name parameter; a result description expression is required. /UPDATED States whether output files (benchmark, difference, and result files) exist for result descriptions with the updated comparison status. The default is to display information for the current result description. If the benchmark file exists, its file specification is displayed. If you include an output file qualifier with the /UPDATED qualifier, the specified output files are displayed for result descriptions with the updated comparison status. An updated test is a test whose benchmark file was created from its result file since the time when the test was last executed. An updated test does not have a result or difference file. You cannot specify a comparison status qualifier with a result description name parameter; a result description expression is required. 5 Example DTM_REVIEW> SHOW/UNSUCCESSFUL Result Description YYY Comparison Status : Unsuccessful Benchmark File is DUA1:[USER01.DTM.DTMLIB]YYY.BMK Result file is present Difference file is present DTM_REVIEW> This example displays all the unsuccessful result descriptions in a collection. 4 SPAWN Creates a subprocess of the current Digital Test Manager session. Format SPAWN [command] [/qualifier...] 5 Command_Qualifiers /CARRIAGE_CONTROL /CARRIAGE_CONTROL /NOCARRIAGE_CONTROL Determines whether carriage control or line feed characters or both are prefixed to the prompt string of the subprocess. The default is the current setting of the parent process. /CLI /CLI[=cli] /NOCLI Specifies an alternate command language interpreter (CLI) for the subprocess to use. The CLI you specify must be located in SYS$SYSTEM and have the file type .EXE. The default is the CLI the parent process uses. /INPUT /INPUT=file-specification Specifies an input file containing one or more commands for the spawned subprocess to execute. If you specify a command with an input file, the command is processed before the commands in the input file. The subprocess terminates when processing is complete. You cannot use wildcards in the file specification. /KEYPAD /KEYPAD (D) /NOKEYPAD Determines whether DCL keypad symbols and the current DCL keypad state are copied from the DCL keypad in the parent process to the subprocess. Use the /NOKEYPAD qualifier if you do not want the key settings to be copied. /LOGICAL_NAMES /LOGICAL_NAMES (D) /NOLOGICAL_NAMES Determines whether the system passes process logical names and logical name tables to the subprocess, except those marked CONFINE or created in executive or kernel mode. /NOTIFY /NOTIFY /NONOTIFY (D) Determines whether a message is sent to the terminal to notify you that the subprocess has completed or aborted. Do not specify /NOTIFY unless you also specify the /NOWAIT qualifier. /OUTPUT /OUTPUT=file-specification Specifies the output file to which the output of the SPAWN operation is to be written. The default is to direct the output to the current SYS$OUTPUT device. When you specify /NOWAIT, you should use /OUTPUT to specify an output other than SYS$OUTPUT to prevent the terminal from being used by both processes simultaneously. /PROCESS /PROCESS=subprocess-name Specifies the name of the subprocess to be created. The default is USERNAME_n (where n denotes a unique number). /PROMPT /PROMPT[=string] Specifies the DCL-prompt string for the subprocess. The default is to copy the current prompt string from the parent process. If you specify /PROMPT but do not specify a string, the default prompt is displayed. /SYMBOLS /SYMBOLS (D) /NOSYMBOLS Determines whether the system passes DCL global and local symbols to the subprocess. /WAIT /WAIT (D) /NOWAIT Controls whether the system waits until the subprocess is completed before enabling more commands to be issued to the parent process. The /NOWAIT qualifier enables you to enter more commands while the specified subprocess is running. When you specify /NOWAIT, you should also specify /OUTPUT to direct output to a file (rather than to the screen). This prevents the terminal from being used by both processes simultaneously. 5 Example DTM_REVIEW> SPAWN MAIL You have 1 new message. MAIL> This example spawns the OpenVMS MAIL Utility from the Digital Test Manager subsystem. Enter the ATTACH command to terminate the MAIL session and return to the Digital Test Manager system level. 4 UPDATE Makes the result file for the specified result descriptions the new benchmark file and deletes the previous benchmark file if it resides in the Digital Test Manager library. Format UPDATE [result-description-expression] [/qualifier...] "remark" 5 Command_Qualifiers /CONFIRM /CONFIRM /NOCONFIRM (D) Controls whether Digital Test Manager displays each test name before updating it and prompts you to confirm whether you want the test results updated. If you specify a wildcard result description expression, Digital Test Manager automatically prompts you. /LOG /LOG (D) /NOLOG Controls whether Digital Test Manager displays informational and success messages on your screen. 5 Example DTM_REVIEW> SELECT MSGTEST Result Description MSGTEST Comparison Status : Unsuccessful DTM_REVIEW> UPDATE %DTM_I_UPDATED, the benchmark for test MSGTEST has been updated DTM_REVIEW> This example selects the MSGTEST test results and then uses the UPDATE command to replace the current benchmark file with the test results. 3 Keypad Review Subsystem Keypad +-------------+-------------+-------------+-------------+ | PF1 | PF2 | PF3 | PF4 | | GOLD | HELP KEYPAD | | | | | HELP | | | +-------------+-------------+-------------+-------------+ | 7 | 8 | 9 | - | | SHOW/DIF | SHOW/RES | SHOW/BEN | SHOW/SUM | | PRINT/DIF | PRINT/RES | PRINT/BEN | | +-------------+-------------+-------------+-------------+ | 4 | 5 | 6 | , | | PRINT/NOW | INSERT | UPDATE | SPAWN | | | | | ATTACH/PAR | +-------------+-------------+-------------+-------------+ | 1 | 2 | 3 | ENTER | | NEXT/UNSUCC | NEXT/NEW | NEXT/UPDATE | | | BACK/UNSUCC | BACK/NEW | BACK/UPDATE | | +-------------+-------------+-------------+ | | 0 | . | | | NEXT | FIRST | | | BACK | LAST | | +---------------------------+-------------+-------------+ 2 RUN Executes a collection interactively producing result files that are subsequently compared with benchmark files. Format RUN collection-name [/qualifier...] "remark" 3 Command_Qualifiers /CONFIRM /CONFIRM (D) /NOCONFIRM Controls whether Digital Test Manager prompts for confirmation when you rerun a collection. Valid responses are Yes, No, All, or Quit. /LOG /LOG (D) /NOLOG Controls whether Digital Test Manager displays informational and success messages on your screen. /LOG_FILE /LOG_FILE=file-specification /NOLOG_FILE Specifies whether a log file for the collection is to be created and where the contents of the log file is to be displayed. This file is similar in content to the log file created when you issue the Digital Test Manager SUBMIT command to run a collection of tests in batch mode. The log file contains output the test run generates other than the output from the test itself, such as output the prologue and epilogue files generate. The /LOG_FILE qualifier creates a log file in the specified file. The output is directed to SYS$OUTPUT. The /NOLOG_FILE qualifier suppresses the creation of a log file. /OUTPUT /OUTPUT=file-specification /NOOUTPUT Specifies where a copy of the output of the RUN command (the test result files) is displayed or written. The /OUTPUT qualifier directs the output to SYS$OUTPUT or to the specified file or device. The /NOOUTPUT qualifier suppresses output. 3 Example DTM> RUN SEND_MAIL_TEST "simple test of SEND_MAIL_TEST command" Starting SEND_MAIL_TEST test run... %DTM-I-BEGIN, your interactive test session is now beginning... . . . %DTM-S-CONCLUDED, your interactive test session has concluded Performing post-run cleanup with comparison... DTM-I-SUCCEEDED, the comparison for test SEND_MAIL_TEST succeeded DTM-S-COMPARED, collection SEND_MAIL_TEST compared DTM> This example executes the collection SEND_MAIL_TEST interactively. 2 SET 3 BENCHMARK_DIRECTORY Specifies the default directory that Digital Test Manager searches for benchmark files. Format SET BENCHMARK_DIRECTORY [directory-specification] [/qualifier] "remark" SET NOBENCHMARK_DIRECTORY ["remark"] 4 Command_Qualifier /LOG /LOG (D) /NOLOG Controls whether Digital Test Manager displays informational and success messages on your screen. 4 Example DTM> SET BENCHMARK_DIRECTORY DUA0:[USER01.BMK] _Remark: New default benchmark directory %DTM-S-NEWDEF, DUA0:[USER01.BMK] is the new default collection benchmark directory DTM> This example establishes a new default benchmark directory for the library. 3 EPILOGUE Establishes the specified file as the default collection epilogue file for all subsequently created collections. Format SET EPILOGUE file-specification [/qualifier] "remark" SET NOEPILOGUE "remark" 4 Command_Qualifier /LOG /LOG (D) /NOLOG Controls whether Digital Test Manager displays informational and success messages on your screen. 4 Examples 1. DTM> SET EPILOGUE DUA0:[USER01.DTMEPI]EPILOGUE.COM "" %DTM-S-NEWDEF, DUA0:[USER01.DTMEPI]EPILOGUE.COM is the new default collection epilogue DTM> This example specifies a file as the default collection epilogue file for subsequently created collections. 2. DTM> SET NOEPILOGUE "canceling epilogue" DTM-S-DEFCANCEL, default epilogue canceled DTM> This example cancels a default collection epilogue file. 3 LIBRARY Selects an existing Digital Test Manager library. Format SET LIBRARY directory-specification [/qualifier...] 4 Command_Qualifiers /LOG /LOG (D) /NOLOG Controls whether Digital Test Manager displays informational and success messages on your screen. /VERIFY /VERIFY (D) /NOVERIFY Specifies whether Digital Test Manager is to verify that the specified directory is a valid Digital Test Manager library. The /VERIFY qualifier causes Digital Test Manager to verify that the specified directory is a valid Digital Test Manager library before selecting it as the current Digital Test Manager library. If the specified directory is not a valid library, Digital Test Manager issues an error message. The /NOVERIFY qualifier causes Digital Test Manager to select the library without verifying that it is a valid Digital Test Manager library. You must specify a valid Digital Test Manager library. 4 Example DTM> SET LIBRARY [.DTMLIB] %DTM-S-LIBIS, Digital Test Manager library is DUA0:[USER01.DTMLIB] DTM> This example selects a Digital Test Manager library. 3 PROLOGUE Establishes the specified file as the default collection prologue file for all subsequently created collections. Format SET PROLOGUE file-specification [/qualifier] "remark" SET NOPROLOGUE "remark" 4 Command_Qualifier /LOG /LOG (D) /NOLOG Controls whether Digital Test Manager displays informational and success messages on your screen. 4 Examples 1. DTM> SET PROLOGUE DUA0:[USER01.DTMPRO]PROLOGUE.COM "" %DTM-S-NEWDEF, DUA0:[USER01.DTMPRO]prologue.com is the new default collection prologue. DTM> This example specifies a default collection prologue file. 2. DTM> SET NOPROLOGUE "canceling prologue" DTM-S-DEFCANCEL, Default prologue canceled DTM> This example cancels a default collection prologue file. 3 TEMPLATE_DIRECTORY Establishes the default directory that Digital Test Manager searches for test template files. Format SET TEMPLATE_DIRECTORY directory-specification [/qualifier] "remark" SET NOTEMPLATE_DIRECTORY "remark" 4 Command_Qualifier /LOG /LOG (D) /NOLOG Controls whether Digital Test Manager displays informational and success messages on your screen. 4 Example DTM> SET TEMPLATE_DIRECTORY DUA0:[USER01.TEMPLATE] _Remark: New default template directory %DTM-S-NEWDEF, DUA0:[USER01.TEMPLATE] is the new default collection template directory DTM> This example establishes a new default template directory for the library. 2 SHOW 3 ALL Displays a summary describing the current library. Format SHOW ALL [/qualifier] 4 Command_Qualifier /OUTPUT /OUTPUT[=file-specification] Sends the SHOW ALL information to the specified file. If you specify the file name but omit the file type, the file type defaults to .LIS. The output is sent to SYS$OUTPUT. 4 Example DTM> SHOW ALL Description of Digital Test Manager Library DBA1$:[project.dsrlib] Default template directory: DUA0:[USER01.TEMP] "Default template library" Default benchmark directory: DUA0:[USER01.BMK] "Default benchmark library" Default collection prologue: DUA0:[USER01.PROEPILIB]PROLOGUE_1.COM Default collection epilogue: DUA0:[USER01.PROEPILIB]EPILOGUE_1.COM Number of collections: 25 Number of test descriptions: 48 Number of groups: 8 Number of variables: 7 DTM> This example describes the current Digital Test Manager library. 3 BENCHMARK_DIRECTORY Displays the directory specification for the current default benchmark directory. Format SHOW BENCHMARK_DIRECTORY [/qualifier] 4 Command_Qualifier /OUTPUT /OUTPUT[=file-specification] Sends the requested information to a specified file. If you specify the file name but omit the file type, the file type defaults to .LIS. The output is sent to SYS$OUTPUT. 4 Example DTM> SHOW BENCHMARK_DIRECTORY DUA0:[USER01.BMK] "Default benchmark library" DTM> This command displays the directory specification for the current default benchmark directory. 3 COLLECTION Displays information about collections in the current Digital Test Manager library. Format SHOW COLLECTION collection-expression [/qualifier...] 4 Command_Qualifiers /BENCHMARK_DIRECTORY Displays the directory specification of the benchmark directory used by this collection. /BRIEF Displays the collection name. The default is /INTERMEDIATE. /CLASS /CLASS=(keyword=class-name,...) Specifies the optional CMS class for benchmark files and template files stored in CMS libraries. The keywords, BENCHMARK and TEMPLATE, designate the name of the specific set of generations of elements. If you do not specify a class and the file is stored in a CMS library, the latest generation on the main line of descent is used. You can specify the same class names for your benchmark and template files. If you specify both keywords, separate them with a comma and enclose the list in parentheses. If you specify only one keyword, omit the parentheses. /FULL Displays the following output: Collections in the Digital Test Manager Library library-name COLLECTION_NAME NUMBER tests DATE TIME "remark" Command: COMMAND-LINE Status: RUN, COMPARISON, AND REVIEW STATUS Successful count: NUMBER Unsuccessful count: NUMBER New test count: NUMBER Updated test count: NUMBER Test not run count: NUMBER Comparisons aborted: NUMBER Default template directory: DIRECTORY_SPECIFICATION Template class: CLASS_NAME Default benchmark directory: DIRECTORY_SPECIFICATION Benchmark class: CLASS_NAME Prologue: FILE_SPECIFICATION Epilogue: FILE_SPECIFICATION Last Review: DATE TIME Result Description COLLECTION_NAME Comparison Status: Successful Benchmark file is device:[username]COLLECTION_NAME.BMK Result file does not exist Difference file does not exist A result description for each test in the collection follows this display. A result description lists the test name and its comparison status and the file specifications for the benchmark, result, and difference files. The default is /INTERMEDIATE. /INTERMEDIATE Displays the following output: Collections in the Digital Test Manager Library library-name COLLECTION NAME NUMBER tests DATE TIME "remark" Command: COMMAND-LINE Status: RUN, COMPARISON, AND REVIEW STATUS Successful count: NUMBER Unsuccessful count: NUMBER New test count: NUMBER Updated test count: NUMBER Test not run count: NUMBER Comparisons aborted: NUMBER /OUTPUT /OUTPUT[=file-specification] Sends the SHOW COLLECTION information to the specified file. If you specify the file name but omit the file type, the file type defaults to .LIS. The output is sent to SYS$OUTPUT. /TEMPLATE_DIRECTORY Displays the directory specification of the template directory used by this collection. Displays the directory specification of the default directory for the current library. 4 Example DTM> SHOW COLLECTION/BRIEF Collections in Digital Test Manager Library DUA0:[USER01.DTMLIB] MAIL_COLL MAIL_SEND_COLL MAIL_SHOW_COLL DTM> This command lists the names of all collections in the current library. 3 EPILOGUE Displays the file specification for the default epilogue file for collections. Format SHOW EPILOGUE [/qualifier] 4 Command_Qualifier /OUTPUT /OUTPUT[=file-specification] Sends the requested information to the specified file. If you specify the file name but omit the file type, the file type defaults to .LIS. The output is sent to SYS$OUTPUT. 4 Example DTM> SHOW EPILOGUE DUA0:[USER01.PROEPILIB]EPILOGUE_1.COM "Default collection epilogue file" DTM> This example displays the file specification for the default collection epilogue file. 3 GROUP Displays the contents of one or more groups. Format SHOW GROUP group-expression [/qualifier...] 4 Command_Qualifiers /BRIEF Lists the group name only. You cannot specify both the /CONTENTS and /BRIEF qualifiers with the same command. /CONTENTS /CONTENTS[=n] /CONTENTS[=ALL] /NOCONTENTS Displays the name of each group and the names of all test descriptions and groups that are contained in the specified groups. The default is /CONTENTS=1. The /CONTENTS=n qualifier displays this information for n levels of groups within each specified group. If n is greater than one, all nested groups for n levels are expanded and displayed. The /CONTENTS=ALL qualifier displays this information for all groups within each group. The /NOCONTENTS qualifier displays the group names only. /FULL Displays the same output as the /CONTENTS=ALL qualifier. /INTERMEDIATE Lists the group name and any remark added during the creation, modification, or copying of the group. This is the default. /MEMBER Lists the groups of which the specified groups are members. /OUTPUT /OUTPUT[=file-specification] Sends the requested information to the specified file. If you specify the file name but omit the file type, the file type defaults to .LIS. The output is sent to SYS$OUTPUT. 4 Example DTM> SHOW GROUP/CONTENTS=ALL MARGINS Groups in Digital Test Manager Library DISK$USER01:[PROJECT.DTMLIB] MARGINS "test of margin commands" LEFTMARGINS/GROUP LMTEST1 LMTEST2 RIGHTMARGINS/GROUP RMTEST1 RMTEST2 TEST1 DTM> This example displays the contents of the MARGINS group. Because /CONTENTS=ALL is specified, each group, test description, and remark is listed. 3 HISTORY Displays a chronological list of the transactions performed on your Digital Test Manager library. Format SHOW HISTORY [object-expression] [/qualifier...] 4 Command_Qualifiers /BEFORE /BEFORE=time Lists all history information prior to a specified date. The time is the current date and time, and the information displayed is whatever was logged prior to the SHOW HISTORY command. The time value can be an absolute, delta, or combination time value, or one of the following keywords: TODAY, TOMORROW, or YESTERDAY. /OUTPUT /OUTPUT=file-specification Sends the requested information to the specified file. If you specify the file name but omit the file type, the file type defaults to .LIS. The output is sent to SYS$OUTPUT. /SINCE /SINCE=time Specifies that only those history entries dated on or after the given time are to be displayed. All transactions recorded since the library was created are displayed. The time value can be an absolute, delta, or combination time value, or one of the following keywords: TODAY, TOMORROW, or YESTERDAY. If you specify the /SINCE qualifier but do not specify a value, Digital Test Manager defaults to /SINCE=TODAY. /TRANSACTION /TRANSACTION=(keyword,...) /NOTRANSACTION=(keyword,...) Displays all transaction records generated by the commands associated with the keywords you specify. The default is to list transaction records for all transactions in the Digital Test Manager library. The valid keyword values are as follows: Keyword Meaning ALL Displays all transactions recorded in the history file COPY Displays all COPY commands CREATE Displays all CREATE commands DELETE Displays all DELETE commands INSERT Displays all INSERT commands MODIFY Displays all MODIFY commands RECORD Displays all RECORD commands RECREATE Displays all RECREATE commands REMARK Displays all REMARK commands REMOVE Displays all REMOVE commands REVIEW Displays all REVIEW commands RUN Displays all RUN commands SET Displays all SET commands STOP Displays all STOP commands SUBMIT Displays all SUBMIT commands UPDATE Displays all Review UPDATE commands VERIFY Displays all VERIFY commands If you specify more than one command, you must enclose the list of commands in parentheses and separate them with commas. The /TRANSACTION qualifier directs Digital Test Manager to list transaction records only for the listed commands. The /NOTRANSACTION qualifier directs Digital Test Manager to list transaction records for all commands except the listed commands. /USER /USER=user-name Lists in chronological order the library transactions performed by the specified user. You cannot use wildcards in user names. 4 Example DTM> SHOW HISTORY History in Digital Test Manager Library DUA0:[USER01.DTMLIB] 08-JAN-86 15:33:59 SMITH CREATE LIBRARY DUA1:[USER01.DTMLIB] "New Digital Test Manager library" 08-JAN-86 15:55:45 SMITH CREATE TEST_DESCRIPTION RMTEST "Run MAIL test" 08-JAN-86 16:15:35 SMITH CREATE TEST_DESCRIPTION MEMO_TEST "First interactive test of memo template" . . . DTM> This command displays the history file for the current library. 3 LIBRARY Displays the directory specification of the current Digital Test Manager library. Format SHOW LIBRARY [/qualifier] 4 Command_Qualifier /OUTPUT /OUTPUT[=file-specification] Sends the requested information to the specified file. If you specify the file name but omit the file type, the file type defaults to .LIS. The output is sent to SYS$OUTPUT. 4 Example DTM> SHOW LIBRARY Your Digital Test Manager library is DUA0:[USER01.DTMLIB] DTM> This example displays your current Digital Test Manager library. 3 PROLOGUE Displays the file specification of the default prologue file for collections. Format SHOW PROLOGUE [/qualifier] 4 Command_Qualifier /OUTPUT /OUTPUT[=file-specification] Sends the requested information to the specified file. If you specify the file name but omit the file type, the file type defaults to .LIS. The output is sent to SYS$OUTPUT. 4 Example DTM> SHOW PROLOGUE DUA0:[USER01.PROEPILIB]PROLOGUE_1.COM "Default collection prologue file" DTM> This example displays the file specification for the default collection prologue file. 3 TEMPLATE_DIRECTORY Displays the directory specification for the default directory that contains the template files. Format SHOW TEMPLATE_DIRECTORY [/qualifier] 4 Command_Qualifier /OUTPUT /OUTPUT[=file-specification] Sends the requested information to a specified file. If you specify the file name but omit the file type, the file type defaults to .LIS. The output is sent to SYS$OUTPUT. 4 Example DTM> SHOW TEMPLATE_DIRECTORY DUA0:[USER01.TEMPLATE] "Default template library" DTM> This example displays the directory specification for the current default template directory. 3 TEST_DESCRIPTION Displays the files and groups associated with one or more test descriptions. Format SHOW TEST_DESCRIPTION [test-group-expression] [/qualifier...] 4 Restrictions o The /COMMAND qualifier applies to DECwindows tests only. o The /FILTER qualifier applies to noninteractive and terminal tests only. 4 Command_Qualifiers /BENCHMARK Displays the file specification for the benchmark file associated with the specified test description. If you use the default benchmark when you create the test description, the benchmark file specification is displayed in the following format: test-name.BMK /BRIEF Displays the test name. /COMMAND Displays the command that is used to begin recording and executing of the test. This qualifier applies to DECwindows tests only. /COMPARISON_TYPE Displays the comparison type associated with the specified test description. /EPILOGUE Displays the file specification for the epilogue file associated with the specified test description. /FILTER Displays the names for all filters associated with the specified test description. /FULL Displays the contents of all test description fields. The format is as follows: Test descriptions in Digital Test Manager library library-name Test_name "remark" Template = file-name Benchmark = file-name Prologue = file-name Epilogue = file-name Variables = variable-name(s)[=value] Groups = group-name(s) Type = type-name Command = command Filters = filter-type(s) Comparison Type = comparison-type /GROUPS Displays the names of the groups with which the test is affiliated. Because of the existence of the /GROUP parameter qualifier for this command, you cannot abbreviate the /GROUPS qualifier. /INTERMEDIATE Displays the contents of the benchmark, template, prologue, and epilogue test description fields. The format is as follows: Test descriptions in Digital Test Manager library library-name Test_name "remark" Template = file-name Benchmark = file-name Prologue = file-name Epilogue = file-name This is the default. /OUTPUT /OUTPUT[=file-specification] Sends the requested information to a specified file. If you specify the file name but omit the file type, the file type defaults to .LIS. By default, the output is sent to SYS$OUTPUT. /PROLOGUE Displays the file specification for the prologue file associated with the specified test description. /REMARK Displays the remark associated with the test description. /TEMPLATE Displays the file specification for the template associated with the specified test description. /TYPE Displays the type of the specified test description-NONINTERACTIVE, INTERACTIVE, or DECWINDOWS. /VARIABLE Displays the names and values for all variables associated with the test description. 4 Parameter_Qualifiers /GROUP Identifies the immediately preceding item in the parameter as a group expression. If a test group expression comprises a list, use this qualifier after each item that designates a group. Because of the existence of the /GROUPS qualifier for this command, you cannot abbreviate the /GROUP qualifier. /TEST_DESCRIPTION Identifies the immediately preceding item in the parameter as a test expression. This is the default. 4 Example DTM> SHOW TEST_DESCRIPTION SEND_MAIL_TEST Test descriptions in Digital Test Manager Library DUA0:[USER01.DTMLIB] SEND_MAIL_TEST "MAIL SEND command test" Template = SEND_MAIL_TEST.COM Benchmark = SEND_MAIL_TEST.BMK Prologue = None Specified Epilogue = None Specified DTM> This example displays the contents of the test description SEND_MAIL_TEST. 3 VARIABLE Displays information about the specified variables. Format SHOW VARIABLE variable-expression [/qualifier...] 4 Command_Qualifiers /BRIEF Displays the variable name only. /FULL Displays the name, value, scope, usage, and remark for the variable and lists the tests with which the variable is associated. /INTERMEDIATE Displays the name, value, and remark for the variable. This is the default. /OUTPUT /OUTPUT[=file-specification] Sends the requested information to the specified file. If you specify the file name but omit the file type, the file type defaults to .LIS. The output is sent to SYS$OUTPUT. /REMARK Displays the remark associated with the variable. /SCOPE Displays the scope of the variable. The scope can be either global or local. /TEST_DESCRIPTION Lists the test descriptions with which the variable is associated. /TYPE Displays the type of variable-STRING or NUMERIC. /USAGE Displays the use of the variable. The use can be either as a symbol or as a logical. /VALUE Displays the variable's default value. If no value has been supplied, the null value is displayed. 4 Example DTM> SHOW VARIABLE /VALUE INPUT_FILE Variables in the Digital Test Manager library DUA0:[USER01.PROJECT] INPUT_FILE "input file for DSR tests" Value = INPUT.RNO DTM> This example displays the value of the variable INPUT_FILE. 3 VERSION Displays the version number for Digital Test Manager currently in use on the system. Format SHOW VERSION [/qualifier] 4 Command_Qualifier /OUTPUT /OUTPUT[=file-specification] Sends requested information to the specified file. If you specify the file name but omit the file type, the file type defaults to .LIS. The output is sent to SYS$OUTPUT. 4 Example DTM> SHOW VERSION Digital Test Manager Version 4.3 DTM> This example displays the version number of Digital Test Manager. 2 SPAWN Creates a subprocess from the current Digital Test Manager session-the parent process. Format SPAWN [command] [/qualifier...] 3 Command_Qualifiers /CARRIAGE_CONTROL /CARRIAGE_CONTROL /NOCARRIAGE_CONTROL Determines whether carriage control characters or line feed characters, or both are prefixed to the DCL-prompt string of the subprocess. The default is the current setting of the parent process. /CLI /CLI[=cli] /NOCLI Specifies an alternate command language interpreter (CLI) for the subprocess to use. The default is the CLI the parent process uses. The CLI you specify must be located in SYS$SYSTEM and have the file type .EXE. /INPUT /INPUT=file-specification Specifies an input file containing one or more commands for the spawned subprocess to execute. If you specify a command with an input file, the command is processed before the commands in the input file. The subprocess terminates when processing is complete. You cannot use wildcards in the file specification. /KEYPAD /KEYPAD (D) /NOKEYPAD Determines whether DCL keypad symbols and the current DCL keypad state are copied from the parent process to the subprocess. Use the /NOKEYPAD qualifier if you do not want the key settings to be copied. /LOGICAL_NAMES /LOGICAL_NAMES (D) /NOLOGICAL_NAMES Determines whether the system passes process logical names and logical name tables to the subprocess, except those marked CONFINE or those created in executive or kernel mode. /NOTIFY /NOTIFY /NONOTIFY (D) Determines whether a message is sent to your terminal to notify you that your subprocess has been completed or aborted. You must specify the /NOWAIT qualifier with the /NOTIFY qualifier. /OUTPUT /OUTPUT=file-specification Specifies the output file to which the output of the SPAWN operation is to be written. If you specify the /NOWAIT qualifier, use the /OUTPUT qualifier to specify an output other than SYS$OUTPUT to prevent your terminal from being used by both processes simultaneously. The default is to direct output to the current SYS$OUTPUT device. /PROCESS /PROCESS=subprocess-name Specifies the name of the subprocess to be created. The default name for the subprocess is USERNAME_n (where n denotes a unique number). /PROMPT /PROMPT[=string] Specifies the prompt string for the subprocess. If you specify the /PROMPT qualifier but do not specify a string, the default prompt is displayed. The default is to copy the current prompt string from the parent process. /SYMBOLS /SYMBOLS (D) /NOSYMBOLS Determines whether the system passes DCL global and local symbols to the subprocess. /WAIT /WAIT (D) /NOWAIT Controls whether the system waits until the subprocess is completed before allowing more commands to be issued by the parent process. The /NOWAIT qualifier enables you to enter more commands while the specified subprocess is running. If you specify the /NOWAIT qualifier, you should also specify /OUTPUT to direct output to a file (rather than to the screen). This prevents your terminal from being used by both processes simultaneously. 3 Example DTM> SPAWN MAIL You have 1 new message. MAIL> This example spawns the OpenVMS MAIL Utility from the Digital Test Manager subsystem. Enter the ATTACH command to terminate the MAIL session and return to the Digital Test Manager system level. 2 STOP Stops a collection that has been submitted to a batch queue. Format STOP collection-name [/qualifier...] "remark" 3 Command_Qualifiers /CONFIRM /CONFIRM /NOCONFIRM (D) Controls whether Digital Test Manager prompts you to confirm that you want to stop the collection. /LOG /LOG (D) /NOLOG Controls whether Digital Test Manager displays informational and success messages on your screen. 3 Example DTM> STOP MAIL_COLL/CONFIRM "Stopping run of MAIL_COLL" Confirm stop of collection MAIL_COLL [Y/N] (N): Y %DTM-S-COLSTOPPED, collection MAIL_COLL has been stopped DTM> This example stops collection MAIL_COLL that is executing in batch. 2 SUBMIT Executes a collection in batch producing result files that are subsequently compared with benchmark files. Format SUBMIT collection-name [/qualifier...] "remark" 3 Restrictions o You can submit collections that contain DECwindows tests but you must be logged into the DECwindows environment and initialize it for testing. 3 Command_Qualifiers /CONFIRM /CONFIRM /NOCONFIRM (D) Controls whether Digital Test Manager prompts you to confirm that you want to submit the collection again if it has not been reviewed. If you have executed but not reviewed a collection, you are prompted to confirm resubmission of the collection. /KEEP /KEEP (D) /NOKEEP Controls whether the log file is deleted after is it printed. /LOG /LOG (D) /NOLOG Controls whether Digital Test Manager displays informational and success messages on your screen. 3 DCL_SUBMIT_qualifiers You can use the following DCL SUBMIT command qualifiers with the SUBMIT command: /AFTER /CHARACTERISTICS /CPUTIME /[NO]HOLD /[NO]LOG_FILE /NAME /[NO]NOTIFY /[NO]PRINTER /PRIORITY /QUEUE /USER /WSDEFAULT /WSEXTENT /WSQUOTA See the OpenVMS DCL Dictionary for more information about these qualifiers. 3 Example DTM> SUBMIT MAIL_COLL/NOTIFY/LOG_FILE=[]/QUEUE=SYS$LARGE %DTM-S-SUBMITTED, collection MAIL_COLL submitted -DTM-I-TEXT, Job MAIL_COLL (queue SYS$LARGE entry 1000) started on SYS$LARGE DTM> This example submits the collection MAIL_COLL to the batch queue SYS$LARGE. The log file is left in the default directory and you are notified when the collection is finished running. 2 VERIFY Evaluates the integrity of the current Digital Test Manager library and its collections. Format VERIFY [/qualifier...] "remark" 3 Command_Qualifiers /LOG /LOG (D) /NOLOG Controls whether Digital Test Manager displays informational and success messages on your screen. /RECOVER Attempts to restore the current library and its collections to a usable state in the event of a process or job abortion or a system failure. It also cleans up the library by deleting files and directories that Digital Test Manager does not own. /REPAIR /REPAIR /NOREPAIR (D) Attempts to reclaim all loose blocks in the current Digital Test Manager library and to delete illegal files found in the library. If Digital Test Manager encounters a subdirectory of the Digital Test Manager library that contains files and the directory is not associated with a collection, Digital Test Manager issues a confirmation message before deleting the directory. 3 Examples 1. DTM> VERIFY %DTM-I-VERFRE, free space list verified %DTM-I-VERSTR, string list verified %DTM-I-VERCOL, collection list verified %DTM-I-VERGRO, group list verified %DTM-I-VERTD, test description list verified %DTM-I-VERVAR, variables list verified %DTM-I-VERARC, archive list verified %DTM-I-VERHEAD, user header information verified %DTM-I-VERSPACE, contiguous space verified %DTM-I-VERCOLDIR, collection directory structure verified %DTM-S-VERIFIED, Digital Test Manager library DUA0:[USER01.DTMLIB] verified DTM> This example verifies that the current Digital Test Manager library is valid. 2. DTM> VERIFY/RECOVER %DTM-S-RECNOTNEC, recovery is not necessary; Digital Test Manager library DUA0:[USER01.DTMLIB] is in a safe state DTM> This example verifies that the current Digital Test Manager library and its collections are valid and informs you that you do not need to recover the library or its collections. 2 Release_Notes You can find the release notes for versions of Digital Test Manager in SYS$HELP:DTMvvu.RELEASE_NOTES, where vv is the major version number, and u is the update number. For example, the release notes for Version 4.3 would be located in SYS$HELP:DTM043.RELEASE_NOTES. To list all the available Digital Test Manager release notes, specify the following DCL command: $ DIRECTORY SYS$HELP:DTM*.RELEASE_NOTES 2 Control_Variables The following logical variables can be used to control the behavior of certain commands. They are fully described in the manual Guide to DIGITAL Test Manager for OpenVMS Systems or in the product Release Notes. DTM$DATE_FILTER_FIRST DTM$DATE_FILTER_MAX_YEAR DTM$DATE_FILTER_MIN_YEAR DTM$DATE_FILTER_STRING DTM$DATE_MASK_MAX_YEAR DTM$DATE_MASK_MIN_YEAR DTM$DELAY_TIMEOUT DTM$IGNORE_PROLOGUE_ERRORS DTM$OMIT_PRINTABLE_SCREENS DTM$RETAIN_RESULTS DTM$TIME_FILTER_NO_SPACE 2 User_Defined_Filters The user defined filter facility provides a mechanism whereby filters written as DEC Text Processing Utility (DECTPU) programs are automatically executed when tests are run. These filters are referred to as user filters. The implementation enables users to solve easily many filtering problems, often with a single-line program, whilst allowing full access to the facilities of DECTPU to solve more complex cases. To implement a new filter, a file containing the required DECTPU commands is created. There are a number of predefined patterns and a global replace procedure provided which can be used to build the commands. For example, the following command will replace device names that precede a directory with the string "DEVICE": global_replace( identifier + ':[' , 'DEVICE:[' ) The filter can be tested using the /USER_FILTER qualifier to the FILTER command. For example: FILTER/USER_FILTER=DEVICE.TPU TEST.DAT See help on FILTER /USER_FILTER for more information. Alternatively, filters can be developed using the TPU pattern style feature of Language-Sensitive Editor. To associate a user filter with a test, a logical variable starting with the characters "DTM$UF_" is created. The value of the variable is the file specification of the file containing the DECTPU commands. For example: CREATE VARIABLE /LOGICAL DTM$UF_DEVICE "DISK1:[TEST.FILTERS]DEVICE.TPU" The variable is then associated with the test in the usual way, for example: MODIFY TEST /VARIABLE=DTM$UF_DEVICE When the test is run, as part of a collection, the filter will be applied. 3 Variables Variables with names beginning with the string "DTM$UF_" are used to control user filters. These variables must be logical variables but can be global or local. When tests are run that have associated variables whose names begin with the string "DTM$UF_", Digital Test Manager will apply the user filters contained in the files referenced by the value of those variables. Only a single file may be referenced by each variable. The specified files are executed by DEC Text Processing Utility (DECTPU). If more than one user filter variable is associated with a test, the files are executed in the lexicographic order of the variable names. The user filters are applied before any built-in filters that are also specified for the test. User filter files can be located either in OpenVMS directories or in Code Management System (CMS) libraries. Files may be specified using logical names including logical names that specify search lists. Wildcards cannot be used. For files in CMS libraries, the most recent generation on the main line of descent is used. Before the first file is executed the file to be filtered is read into the DECTPU buffer "filter_buffer". Next, the file specified by the logical name DTM$UFDEFINES is executed. The system logical name DTM$UFDEFINES references the file SYS$LIBRARY:DTM$UFDEFINES.TPU, which contains definitions of a global replace procedure and patterns which can be used in building filters. This logical can be redefined to point to a custom file. Any errors in accessing the user filter files or in executing the DECTPU commands will be reported. However, they will not cause the filter operation to fail, and any remaining user and built-in filters will be applied. After all the user filters have been applied, the file being filtered will be written out. If any built-in filters are also specified, they are applied to the newly created file, resulting in a second new version. In order to disable a user filter that is defined with a global variable for a particular test, define the value of the variable for the test as a string containing only spaces. For example: MODIFY TEST CHECK_DEVICES /VARIABLE=DTM$UF_DEVICE=" " 3 Recording_Terminal_Tests When using the RECORD/FILTER command to filter the benchmark produced by recording an interactive terminal test, user filters associated with the test will be applied, provided that the /VARIABLES qualifier is also used. For example: RECORD /FILTER /VARIABLES TERMINAL_TEST1 3 Global_Replace_Procedure The supplied file SYS$LIBRARY:DTM$UFDEFINES.TPU contains a global replace procedure and some predefined patterns that can be used to build filters. The specification of procedure global_replace is as follows: PROCEDURE global_replace ( pattern_to_replace, replacement_string; search_mode, evaluate_replacement, convert_linefeeds) DESCRIPTION: Replace all occurrences of a given pattern with a given string in the buffer "filter_buffer". PARAMETERS: pattern_to_replace The pattern to be replaced. replacement_string The string to be substituted. search_mode (optional) The mode of pattern matching to be used when searching for the pattern. Should be one of: NO_EXACT (default) EXACT TPU$K_SEARCH_CASE TPU$K_SEARCH_DIACRITICAL evaluate_replacement Specifies whether the replacement (optional) string is to be evaluated. Should be one of: OFF, 0 (default) ON, 1 If specified as ON or 1, the replacement string is evaluated before use. This is needed if the replacement string contains any partial pattern variables. In this case, any string literals in the replacement string must be specified as nested strings and partial pattern variables converted to strings using STR. convert_linefeeds Specifies whether any linefeed (optional) characters in the replacement string are to be converted into line breaks. Should be one of: OFF, 0 (default) ON, 1 3 Examples Example 1: Simple Use of procedure global_replace The following example assumes that the disks are named UDISK where is a number, for example UDISK1, UDISK13. This filter replaces such disk names with the string "DISK_NAME": global_replace ( 'UDISK' + number, 'DISK_NAME') The pattern to replace is built from a string literal ('UDISK'), the concatenation operator (+) and the pattern "number" included in the supplied definitions file. The pattern "number" matches a sequence of digits. The replacement string is the string literal 'DISK_NAME'. Example 2: Using the Null Pattern This example uses the supplied "null" pattern with the DECTPU alternation operator to include an optional element in a pattern. Supposing that, in the previous example, some of the disk names do not include the leading "U", for example DISK7. The following filter replaces disk names with or without the leading "U": global_replace ( ("U"|null) + "DISK" + number, "DISK_NAME") Example 3: Using Pattern Variables The following example filters dates in the form DD-MMM-YYYY, for example 11-OCT-1999. Because it only filters this one form of date, it is quicker than the built-in date filter which filters many different date formats. It is also not the exact equivalent of the built-in date filter in other respects, for example it treats 37-NOV-0999 as a date, but should be sufficient for most purposes. day := any(" 123") + digit; month := "JAN" | "FEB" | "MAR" | "APR" | "MAY" | "JUN" | "JUL" | "AUG" | "SEP" | "OCT" | "NOV" | "DEC"; year := any(digits,4); date := day + "-" + month + "-" + year; global_replace( date, "dd-mmm-yyyy"); This filter defines the pattern variables "day", "month" and "year" which are then used to define the pattern variable "date" used in the call to global_replace. The "day" pattern uses the DECTPU function "any" to match either a space or one of the characters "1", "2" or "3", followed by a digit. The "month" pattern uses the DECTPU pattern alternation operator "|" to specify a list of alternative string literals. The "year" pattern uses the DECTPU function "any" with the supplied pattern "digits". The "4" parameter indicates that exactly 4 digits are to be matched. The "date" pattern concatenates these patterns and linking punctuation. Example 4: Removing Blank Lines This filter removes blank lines using the DECTPU keywords LINE_BEGIN and LINE_END. global_replace( LINE_BEGIN + LINE_END, ''); The LINE_END keyword absorbs the new line. The above filter only replaces lines containing no characters. The following filter also replaces lines containing only spaces and tab characters: global_replace( LINE_BEGIN + (white_space|null) + LINE_END, ''); Example 5: Using Partial Pattern Variables to Retain Context This example demonstrates how to use surrounding text to identify a string to be replaced without also replacing the surrounding text. The following filter replaces the month part of a date with the string "mmm". For example, the string "14-OCT-1999" will be replaced by the string "14-mmm-1999": day := any(" 123") + digit; month := "JAN" | "FEB" | "MAR" | "APR" | "MAY" | "JUN" | "JUL" | "AUG" | "SEP" | "OCT" | "NOV" | "DEC"; year := any(digits,4); date := (day + "-"@day_part) + month + ("-" + year@year_part); global_replace( date, 'str(day_part) + "mmm" + str(year_part)',,ON); The day part of the date and the "-" character are assigned to the partial pattern variable day_part and the year part of the date and preceding "-" assigned to year_part. These partial pattern variables are then included in the replacement string. When partial pattern variable are used in the replacement string they must be evaluated for each replacement. To do this, set the parameter evaluate_replacement to ON, as shown above. When the replacement string is to be evaluated, string literals must be nested inside further quotes. This is most easily done by using single quotes for the outer string and double quotes for any nested string literals, or vice-versa. Also, any partial pattern variables must be converted to strings using the DECTPU procedure STR. Note that including LINE_END in the definition of a partial pattern variable does not have the effect of retaining the line break. See example 6 for a resolution of this problem. Example 6: Using LINE_END for Context If the search pattern contains LINE_END, the matched line break will be removed, causing the next line to be appended to the current line. To use LINE_END to only provide context for the search, the line break must be reinserted. This is done using the parameter convert_linefeeds. If the convert_linefeeds parameter is specified as ON, any linefeed characters appearing in the replacement string are removed and the built-in DECTPU procedure SPLIT_LINE is called at the point of the linefeed character. The following filter replaces any numbers that are the last characters on a line with the string "x": global_replace (number+LINE_END, "x"+lf,,,ON) The "lf" pattern is defined as a linefeed character in the supplied definitions file. If a LINE_END is included in a partial pattern variable, the line break can be retained by specifying the second optional parameter to the DECTPU STR procedure as a linefeed character, for example: global_replace (number+(LINE_END@sep), '"x"+STR(sep,lf)',,ON,ON) The second parameter to STR specifies the string that line breaks occurring in the first parameter should be converted to. Line breaks are retained by specifying the linefeed character and setting the parameter convert_linefeeds to ON. Example 7: Using UNANCHOR to Replace Sections The DECTPU keyword UNANCHOR can be used to replace sections of text delimited by specified strings. The following replaces all text between the strings "/*" and "*/" with the string "/* Text deleted */". The text may run across line boundaries: global_replace ( "/*" + UNANCHOR + "*/", "/* Text deleted */") Note that while a similar effect is possible using the COMPARE/SENTINEL command, the filter can be applied to individual tests, whereas the /SENTINEL qualifier applies only to collections. Example 8: Using Other DECTPU Commands The global_replace procedure can be used for many filtering tasks. However any DECTPU commands can be used to build filters. The file being filtered is read into the buffer "filter_buffer" before the user filters are applied and written out afterwards. The following filter uses the DECTPU EDIT procedure to convert all characters to upper case: EDIT( filter_buffer, UPPER, OFF) Note that while a similar effect is possible using the COMPARE/IGNORE=CASE command, the filter can be applied to individual tests, whereas the IGNORE qualifier applies only to collections. The following filter searches for numbers and replaces them only if they are in a specified range: POSITION (BEGINNING_OF (filter_buffer)); LOOP found_range := SEARCH_QUIETLY (number, FORWARD); EXITIF found_range = 0; POSITION (END_OF(found_range)); MOVE_HORIZONTAL(1); value := INT(STR(found_range)); IF (value>350) AND (value<570) THEN COPY_TEXT ("XXX"); ERASE (found_range); ENDIF; ENDLOOP; The initial POSITION is required to ensure that the whole of the filter_buffer is processed, because the editing point is undefined at the start of each filter. Then, as each number is processed, the editing point is moved to the end of the number. The MOVE_HORIZONTAL procedure call is necessary because the previous POSITION leaves the editing point at the last character of the number, which would result in an immediate match on the next call to SEARCH_QUIETLY.