DTM
*Conan The Librarian (sorry for the slow response - running on an old VAX)
|
VMS Help DTM *Conan The Librarian (sorry for the slow response - running on an old VAX) |
|
Compaq 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.
| 1 - @file-specification |
Executes Digital Test Manager commands contained in the specified
file.
Format
@file-specification
1.1 - 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]
2.1 - Command Qualifiers
2. 1.1 - /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.
2. 1.2 - /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.
2.2 - 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.
| 3 - COMPARE |
Compares the result file produced for each test description in a
collection with its corresponding benchmark file.
Format
COMPARE collection-name [/qualifier...]
3.1 - Command Qualifiers
3. 1.1 - /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.
3. 1.2 - /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.
3. 1.3 - /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
3. 1.4 - /LOG
/LOG (D) /NOLOG Controls whether Digital Test Manager displays informational and success messages on your screen.
3. 1.5 - /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.
3. 1.6 - /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.
3. 1.7 - /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.
3. 1.8 - /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.
3. 1.9 - /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.
3. 1.10 - /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.2 - 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.
| 4 - CONVERT |
4.1 - LIBRARY
Converts Digital Test Manager libraries created with a version of
Digital Test Manager prior to Version 2.0 for use with the current
version of Digital Test Manager.
Format
CONVERT LIBRARY existing-library-name new-library-name
4. 1.1 - Example
$ CREATE/DIRECTORY [project.v1lib] $ DTM DTM> CONVERT LIBRARY [project.V1lib] [project.v2lib] %DTM-S-COPIED, V1 variables copied %DTM-S-COPIED, V1 groups copied %DTM-S-COPIED, V1 test descriptions copied -DTM-S-CONVERTED, your V1 library has been successfully converted to V2 DTM> This example first creates a new directory to contain the converted library. Then the Digital Test Manager system is entered and the existing library is converted. The benchmark files are not copied because they are stored outside the Digital Test Manager library in a benchmark directory. They are accessible to the new library.
| 5 - COPY |
5.1 - TEST_DESCRIPTION
Copies an existing test description.
Format
COPY TEST_DESCRIPTION test-name1 test-name2 [/qualifier...]
"remark"
5. 1.1 - Restrictions
o The /COMMAND qualifier applies to DECwindows tests only.
o The /NOFILTERS qualifier applies to interactive and
noninteractive terminal tests only.
5. 1.2 - Command Qualifiers
5. 1. 2.1 - /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.
5. 1. 2.2 - /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.
5. 1. 2.3 - /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.
5. 1. 2.4 - /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.
5. 1. 2.5 - /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.
5. 1. 2.6 - /LOG
/LOG (D) /NOLOG Controls whether Digital Test Manager displays informational and success messages on your screen.
5. 1. 2.7 - /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.
5. 1. 2.8 - /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.
5. 1. 2.9 - /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.
5. 1. 2.10 - /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.
5. 1.3 - 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.
| 6 - CREATE |
6.1 - COLLECTION
Designates a set of tests as a collection.
Format
CREATE COLLECTION collection-name test-group-expression
[/qualifier...] "remark"
6. 1.1 - Command Qualifiers
6. 1. 1.1 - /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.
6. 1. 1.2 - /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.
6. 1. 1.3 - /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.
6. 1. 1.4 - /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.
6. 1. 1.5 - /LOG
/LOG (D) /NOLOG Controls whether Digital Test Manager displays informational and success messages on your screen.
6. 1. 1.6 - /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.
6. 1. 1.7 - /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.
6. 1. 1.8 - /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.
6. 1. 1.9 - /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.
6. 1. 1.10 - /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.
6. 1. 1.11 - /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.
6. 1. 1.12 - /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.
6. 1. 1.13 - /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.
6. 1.2 - Parameter Qualifiers
6. 1. 2.1 - /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.
6. 1. 2.2 - /TEST_DESCRIPTION
Identifies the immediately preceding item in the test group expression as a test expression. This is the default.
6. 1.3 - 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.
6.2 - GROUP
Creates a group in the Digital Test Manager library.
Format
CREATE GROUP group-name [/qualifier] "remark"
6. 2.1 - Command Qualifier
6. 2. 1.1 - /LOG
/LOG (D) /NOLOG Controls whether Digital Test Manager displays informational and success messages on your screen.
6. 2.2 - 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.
6.3 - LIBRARY
Creates a Digital Test Manager library in an empty OpenVMS directory.
Format
CREATE LIBRARY directory-specification [/qualifier] "remark"
6. 3.1 - 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.
6. 3.2 - Command Qualifier
6. 3. 2.1 - /LOG
/LOG (D) /NOLOG Controls whether Digital Test Manager displays informational and success messages on your screen.
6. 3.3 - 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.
6.4 - TEST_DESCRIPTION
Creates a test description in the Digital Test Manager library.
Format
CREATE TEST_DESCRIPTION test-name [/qualifier...] "remark"
6. 4.1 - Restrictions
o The /COMMAND qualifier applies to DECwindows tests only.
o The /FILTER qualifier applies to noninteractive and terminal
tests only.
6. 4.2 - Command Qualifiers
6. 4. 2.1 - /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.
6. 4. 2.2 - /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.
6. 4. 2.3 - /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.
6. 4. 2.4 - /DECWINDOWS
Specifies that the test being created is marked as a DECwindows test.
6. 4. 2.5 - /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.
6. 4. 2.6 - /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.
6. 4. 2.7 - /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.
6. 4. 2.8 - /LOG
/LOG (D) /NOLOG Controls whether Digital Test Manager displays informational and success messages on your screen.
6. 4. 2.9 - /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.
6. 4. 2.10 - /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.
6. 4. 2.11 - /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.
6. 4.3 - 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.
6.5 - VARIABLE
Defines a variable in the Digital Test Manager library.
Format
CREATE VARIABLE variable-name variable-value [/qualifier...]
"remark"
6. 5.1 - Command Qualifiers
6. 5. 1.1 - /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.
6. 5. 1.2 - /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.
6. 5. 1.3 - /LOG
/LOG (D) /NOLOG Controls whether Digital Test Manager displays informational and success messages on your screen.
6. 5. 1.4 - /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.
6. 5. 1.5 - /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.
6. 5. 1.6 - /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.
6. 5. 1.7 - /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.
6. 5.2 - 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.
| 7 - DEFINE |
Use DEFINE/KEY to define a key to execute a command string.
Format
DEFINE/KEY key-name "command-string" [/qualifier...]
7.1 - /KEY
Use DEFINE/KEY to define a key to execute a command string.
Format
DEFINE/KEY key-name "command-string" [/qualifier...]
7. 1.1 - 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.
7. 1.2 - Command Qualifiers
7. 1. 2.1 - /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.
7. 1. 2.2 - /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.
7. 1. 2.3 - /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.
7. 1. 2.4 - /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.
7. 1. 2.5 - /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.
7. 1.3 - 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>
| 8 - DELETE |
8.1 - 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"
8. 1.1 - Command Qualifiers
8. 1. 1.1 - /CONFIRM
/CONFIRM (D) /NOCONFIRM Controls whether Digital Test Manager prompts you to confirm each deletion. Valid responses are Yes, No, All, or Quit.
8. 1. 1.2 - /LOG
/LOG (D) /NOLOG Controls whether Digital Test Manager displays informational and success messages on your screen. The default is /LOG.
8. 1.2 - 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.
8.2 - GROUP
Deletes a group from the Digital Test Manager library.
Format
DELETE GROUP group-expression [/qualifier...] "remark"
8. 2.1 - 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.
8. 2.2 - Command Qualifiers
8. 2. 2.1 - /CONFIRM
/CONFIRM (D) /NOCONFIRM Controls whether Digital Test Manager prompts you to confirm each deletion. Valid responses are Yes, No, All, or Quit.
8. 2. 2.2 - /LOG
/LOG (D) /NOLOG Controls whether Digital Test Manager displays informational and success messages on your screen.
8. 2.3 - 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.
8.3 - HISTORY
Deletes history information from the history file.
Format
DELETE HISTORY [/qualifier...] "remark"
8. 3.1 - Command Qualifiers
8. 3. 1.1 - /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.
8. 3. 1.2 - /CONFIRM
/CONFIRM (D) /NOCONFIRM Controls whether Digital Test Manager prompts you to confirm each deletion. Valid responses are Yes, No, All, or Quit.
8. 3. 1.3 - /LOG
/LOG (D) /NOLOG Controls whether Digital Test Manager displays informational and success messages on your screen.
8. 3. 1.4 - /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.
8. 3.2 - 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"
8.4 - TEST_DESCRIPTION
Deletes a test description from the Digital Test Manager library.
Format
DELETE TEST_DESCRIPTION test-expression [/qualifier...]
"remark"
8. 4.1 - 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.
8. 4.2 - Command Qualifiers
8. 4. 2.1 - /CONFIRM
/CONFIRM (D) /NOCONFIRM Controls whether Digital Test Manager prompts you to confirm each deletion. Valid responses are Yes, No, All, or Quit.
8. 4. 2.2 - /LOG
/LOG (D) /NOLOG Controls whether Digital Test Manager displays informational and success messages on your screen.
8. 4.3 - 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.
8.5 - VARIABLE
Deletes specified variables from the Digital Test Manager library.
Format
DELETE VARIABLE variable-expression [/qualifier...] "remark"
8. 5.1 - 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.
8. 5.2 - Command Qualifiers
8. 5. 2.1 - /CONFIRM
/CONFIRM (D) /NOCONFIRM Controls whether Digital Test Manager prompts you to confirm each deletion. Valid responses are Yes, No, All, or Quit.
8. 5. 2.2 - /LOG
/LOG (D) /NOLOG Controls whether Digital Test Manager displays informational and success messages on your screen.
8. 5.3 - 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.
| 9 - DISPLAY |
Displays the benchmark file for a specified interactive terminal
test.
Format
DISPLAY test-name [/qualifier]
9.1 - Command Qualifier
9. 1.1 - /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.
9.2 - 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.
| 10 - DTM |
Invokes the Digital Test Manager. You enter the DTM command at the DCL
prompt ($).
Format
DTM [/qualifier]
10.1 - Command Qualifier
10. 1.1 - /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.
10. 1.2 - /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.
10.2 - Example
$ DTM DTM> This example shows how to invoke the Digital Test Manager system.
| 11 - EXIT |
Terminates a Digital Test Manager session.
Format
EXIT
11.1 - Example
DTM> EXIT $ This example terminates a Digital Test Manager session.
| 12 - EXTRACT |
Extracts an input file from an interactive terminal or DECwindows
session file.
Format
EXTRACT session-file-specification [input-file-specification]
[/qualifier...]
12.1 - Restrictions
o The EXTRACT command is used for interactive terminal and
DECwindows tests only.
o The /TERMINATION_CHARACTER qualifier applies to terminal tests
only.
12.2 - Command Qualifiers
12. 2.1 - /DECWINDOWS
Specifies that the session file is a recorded DECwindows session.
12. 2.2 - /INTERACTIVE
/INTERACTIVE (D) Specifies that the session file is a recorded terminal session.
12. 2.3 - /LOG
/LOG (D) /NOLOG Controls whether Digital Test Manager displays informational and success messages on your screen.
12. 2.4 - /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.
12.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.
| 13 - 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...]
13.1 - Restrictions
o The FILTER command is for use with noninteractive and terminal
tests only.
13.2 - Command Qualifiers
13. 2.1 - /ALL
Specifies that all the filters be run on the specified file.
13. 2.2 - /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
13. 2.3 - /DIRECTORIES
Replaces the directory specification field in the file specification with DISK:[DIRECTORY].
13. 2.4 - /FILE_NAMES
Replaces the file names with FILENAME.EXT.
13. 2.5 - /LOG
/LOG (D) /NOLOG Controls whether Digital Test Manager displays informational and success messages on your screen.
13. 2.6 - /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
13. 2.7 - /TRACE_BACK
Replaces 32-bit memory addresses with xxxxxxxx and 64-bit memory addresses with xxxxxxxx xxxxxxxx.
13. 2.8 - /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 Compaq 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.
13. 2.9 - /VERSION
Replaces file versions with VERSION.
13.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.
| 14 - HELP |
Displays help text for Digital Test Manager and Review subsystem
commands.
Format
HELP [topic]
14.1 - 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.
| 15 - INSERT |
15.1 - GROUP
Places one or more groups in one or more other groups.
Format
INSERT GROUP group-expression1 group-expression2
[/qualifier...] "remark"
15. 1.1 - 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.
15. 1.2 - Command Qualifiers
15. 1. 2.1 - /CONFIRM
/CONFIRM /NOCONFIRM (D) Controls whether Digital Test Manager prompts you to confirm each insertion. Valid responses are Yes, No, All, or Quit.
15. 1. 2.2 - /LOG
/LOG (D) /NOLOG Controls whether Digital Test Manager displays informational and success messages on your screen.
15. 1.3 - 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.
15.2 - TEST_DESCRIPTION
Places one or more test descriptions into one or more groups.
Format
INSERT TEST_DESCRIPTION test-group-expression group-expression
[/qualifier...] "remark"
15. 2.1 - Command Qualifiers
15. 2. 1.1 - /CONFIRM
/CONFIRM /NOCONFIRM (D) Controls whether Digital Test Manager prompts you to confirm each insertion. Valid responses are Yes, No, All, or Quit.
15. 2. 1.2 - /LOG
/LOG (D) /NOLOG Controls whether Digital Test Manager displays informational and success messages on your screen.
15. 2.2 - Parameter Qualifiers
15. 2. 2.1 - /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.
15. 2. 2.2 - /TEST_DESCRIPTION
Identifies the immediately preceding item in a parameter as a test. This is the default.
15. 2.3 - 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.
| 16 - MODIFY |
16.1 - GROUP
Replaces the remark associated with existing groups.
Format
MODIFY GROUP group-expression [/qualifier...] "remark"
16. 1.1 - Command Qualifiers
16. 1. 1.1 - /LOG
/LOG (D) /NOLOG Controls whether Digital Test Manager displays informational and success messages on your screen.
16. 1. 1.2 - /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.
16. 1.2 - 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.
16.2 - TEST_DESCRIPTION
Changes specified field values in existing test descriptions.
Format
MODIFY TEST_DESCRIPTION test-group-expression [/qualifier...]
"remark"
16. 2.1 - Restrictions
o The /COMMAND qualifier applies to DECwindows tests only.
o The /FILTER qualifier applies to noninteractive and terminal
tests only.
16. 2.2 - Command Qualifiers
16. 2. 2.1 - /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.
16. 2. 2.2 - /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.
16. 2. 2.3 - /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.
16. 2. 2.4 - /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.
16. 2. 2.5 - /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.
16. 2. 2.6 - /LOG
/LOG (D) /NOLOG Controls whether Digital Test Manager displays informational and success messages on your screen.
16. 2. 2.7 - /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.
16. 2. 2.8 - /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.
16. 2. 2.9 - /TEMPLATE
/TEMPLATE=file-specification /NOTEMPLATE Specifies whether to replace or disassociated from the template file. A test description must always have a template file.
16. 2. 2.10 - /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.
16. 2.3 - Parameter Qualifiers
16. 2. 3.1 - /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.
16. 2. 3.2 - /TEST_DESCRIPTION
Identifies the immediately preceding item in the parameter as a test expression. This is the default.
16. 2.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.
16.3 - VARIABLE
Modifies variable definitions in the Digital Test Manager library.
Format
MODIFY VARIABLE variable-expression [/qualifier...] "remark"
16. 3.1 - Command Qualifiers
16. 3. 1.1 - /GLOBAL
Makes the variable expression globally accessible. You cannot specify both the /LOCAL and /GLOBAL qualifiers with the same MODIFY VARIABLE command.
16. 3. 1.2 - /LOCAL
Makes the variable expression locally accessible. You cannot specify both the /LOCAL and /GLOBAL qualifiers with the same MODIFY VARIABLE command.
16. 3. 1.3 - /LOG
/LOG (D) /NOLOG Controls whether Digital Test Manager displays informational and success messages on your screen.
16. 3. 1.4 - /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.
16. 3. 1.5 - /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.
16. 3. 1.6 - /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.
16. 3. 1.7 - /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.
16. 3. 1.8 - /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.
16. 3. 1.9 - /VALUE
/VALUE=value Changes the value of the variable. A value specified with the MODIFY VARIABLE command replaces any previous value for the variable.
16. 3.2 - 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.
| 17 - PLAY |
Executes the specified session file and displays the output on
your screen.
Format
PLAY file-specification [/qualifier...]
17.1 - Restrictions
o You cannot play a DECwindows session file on a terminal screen. o The /KEYSYM qualifier applies to DECwindows tests only.
17.2 - Command Qualifiers
17. 2.1 - /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.
17. 2.2 - /COMMAND
/COMMAND=DCL-command Specifies a command action to be executed before playing a DECwindows session file.
17. 2.3 - /DECWINDOWS
Specifies that the session file being played is a DECwindows session file.
17. 2.4 - /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.
17. 2.5 - /INTERACTIVE
/INTERACTIVE (D) Specifies that the session file being played is an interactive terminal session file.
17. 2.6 - /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
17. 2.7 - /LOG
/LOG (D) /NOLOG Controls whether Digital Test Manager displays informational and success messages on your screen.
17. 2.8 - /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.
17. 2.9 - /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.
17.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.
| 18 - RECORD |
Records an interactive terminal or DECwindows test.
Format
RECORD test-name [/qualifier...] "remark"
18.1 - 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.
18.2 - Qualifiers
18. 2.1 - /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.
18. 2.2 - /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.
18. 2.3 - /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.
18. 2.4 - /EPILOGUE
/EPILOGUE /NOEPILOGUE (D) Specifies whether Digital Test Manager is to execute the test epilogue file when interactive recording terminates.
18. 2.5 - /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.
18. 2.6 - /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.
18. 2.7 - /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
18. 2.8 - /LOG
/LOG (D) /NOLOG Controls whether Digital Test Manager displays informational and success messages on your screen.
18. 2.9 - /POINTER_MOTION
/POINTER_MOTION /NOPOINTER_MOTION(D) Specifies whether Digital Test Manager records pointer motion for DECwindows tests.
18. 2.10 - /PROLOGUE
/PROLOGUE /NOPROLOGUE (D) Specifies whether Digital Test Manager is to execute the test prologue file before interactive recording begins.
18. 2.11 - /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.
18. 2.12 - /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.
18. 2.13 - /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.
18.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.
| 19 - RECREATE |
Re-creates a collection, providing the same attributes that were
part of the original collection.
Format
RECREATE collection-name [/qualifier...] "remark"
19.1 - Command Qualifiers
19. 1.1 - /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.
19. 1.2 - /LOG
/LOG (D) /NOLOG Controls whether Digital Test Manager displays informational and success messages on your screen.
19.2 - 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.
| 20 - REMARK |
Places a remark in the Digital Test Manager history file.
Format
REMARK "remark" [/qualifier]
20.1 - Command Qualifier
20. 1.1 - /LOG
/LOG (D) /NOLOG Controls whether Digital Test Manager displays informational and success messages on your screen.
20.2 - 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.
| 21 - REMOVE |
21.1 - GROUP
Removes one or more groups from one or more other groups.
Format
REMOVE GROUP group-expression1 group-expression2
[/qualifier...] "remark"
21. 1.1 - Command Qualifiers
21. 1. 1.1 - /CONFIRM
/CONFIRM (D) /NOCONFIRM Controls whether Digital Test Manager prompts you to confirm each removal. Valid responses are Yes, No, All, or Quit.
21. 1. 1.2 - /LOG
/LOG (D) /NOLOG Controls whether Digital Test Manager displays informational and success messages on your screen.
21. 1.2 - 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.
21.2 - TEST_DESCRIPTION
Removes one or more test descriptions from one or more groups.
Format
REMOVE TEST_DESCRIPTION test-group-expression group-expression
[/qualifier...] "remark"
21. 2.1 - Command Qualifiers
21. 2. 1.1 - /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.
21. 2. 1.2 - /LOG
/LOG (D) /NOLOG Controls whether Digital Test Manager displays informational and success messages on your screen.
21. 2.2 - Parameter Qualifiers
21. 2. 2.1 - /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.
21. 2. 2.2 - /TEST_DESCRIPTION
Identifies the immediately preceding item in the parameter as a test expression. This is the default.
21. 2.3 - 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.
| 22 - REVIEW |
Invokes the Review subsystem to examine and manipulate test
results for a collection of tests.
Format
REVIEW collection-name [/qualifier] ["remark"]
22.1 - 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.
22.2 - Qualifiers
22. 2.1 - /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.
22.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.
22.4 - 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:
22. 4.1 - @file-specification
Executes Digital Test Manager Review subsystem commands contained in
the specified file.
Format
@file-specification
22. 4. 1.1 - Restrictions
o You can only specify Review subsystem commands with this
@file-specification command.
22. 4. 1.2 - 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.
22. 4.2 - ATTACH
Switches control from the current process to another process in
your job.
Format
ATTACH process-name [/qualifier...]
22. 4. 2.1 - Command Qualifiers
22. 4. 2. 1.1 - /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.
22. 4. 2. 1.2 - /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.
22. 4. 2.2 - 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.
22. 4.3 - BACK
Moves you backward through the sequence of result descriptions
being reviewed.
Format
BACK [count] [/qualifier...]
22. 4. 3.1 - Command Qualifiers
22. 4. 3. 1.1 - /COMPARISON_ABORTED
Moves you to the previous result description for a test whose comparison aborted.
22. 4. 3. 1.2 - /NEW
Moves you to the previous result description for a new test.
22. 4. 3. 1.3 - /NOT_RUN
Moves you to the previous result description for a test that did not run.
22. 4. 3. 1.4 - /SUCCESSFUL
Moves you to the previous successfully compared result description.
22. 4. 3. 1.5 - /UNSUCCESSFUL
Moves you to the previous unsuccessfully compared result description.
22. 4. 3. 1.6 - /UPDATED
Moves you to the previous updated result description.
22. 4. 3.2 - Example
DTM_REVIEW> BACK 2
.
.
.
This example displays the result description that is two
positions behind the current result description.
22. 4.4 - DEFINE
Use DEFINE/KEY to define a key to execute a command string.
Format
DEFINE/KEY key-name "command-string" [/qualifier...]
22. 4. 4.1 - /KEY
Use DEFINE/KEY to define a key to execute a command string.
Format
DEFINE/KEY key-name "command-string" [/qualifier...]
22. 4. 4. 1.1 - 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.
22. 4. 4. 1.2 - Command Qualifiers
22. 4. 4. 1. 2.1 - /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.
22. 4. 4. 1. 2.2 - /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.
22. 4. 4. 1. 2.3 - /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.
22. 4. 4. 1. 2.4 - /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.
22. 4. 4. 1. 2.5 - /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.
22. 4. 4. 1.3 - 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.
22. 4.5 - EXIT
Terminates the Review session and returns control to the previous
command level where you invoked the Review subsystem.
Format
EXIT [/qualifier...]
22. 4. 5.1 - Command Qualifiers
22. 4. 5. 1.1 - /NOINSERT
Specifies that a group is not to be created from tests marked with the INSERT command when you exit the Review subsystem.
22. 4. 5. 1.2 - /NOPRINT
Specifies that files marked with the PRINT command are not to be printed when you exit the Review subsystem.
22. 4. 5.2 - Example
DTM_REVIEW> EXIT %DTM-S-EXIT, leaving Review subsystem DTM> This example shows how to exit from the Review subsystem.
22. 4.6 - FIRST
Moves you to the first result description in the collection you
are reviewing.
Format
FIRST
22. 4. 6.1 - Example
DTM_REVIEW> FIRST
.
.
.
This example displays the first result description in a
collection.
22. 4.7 - HELP
Displays help text for Review subsystem commands.
Format
HELP [topic]
22. 4. 7.1 - 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.
22. 4.8 - 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...]
22. 4. 8.1 - Command Qualifiers
22. 4. 8. 1.1 - /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.
22. 4. 8. 1.2 - /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.
22. 4. 8. 1.3 - /NEW
Marks for inclusion test descriptions for new tests. The default is to mark the test description associated with the current result description.
22. 4. 8. 1.4 - /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.
22. 4. 8. 1.5 - /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.
22. 4. 8. 1.6 - /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.
22. 4. 8. 1.7 - /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.
22. 4. 8.2 - 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.
22. 4.9 - LAST
Moves you to the last result description in the collection you are
reviewing.
Format
LAST
22. 4. 9.1 - Example
DTM_REVIEW> LAST
.
.
.
This example displays the last result description in a
collection.
22. 4.10 - 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...]
22. 4. 10.1 - Command Qualifiers
22. 4. 10. 1.1 - /COMPARISON_ABORTED
Moves you to the next result description for a test whose comparison aborted.
22. 4. 10. 1.2 - /NEW
Moves you to the next result description for a new test.
22. 4. 10. 1.3 - /NOT_RUN
Moves you to the next result description for a test that did not run.
22. 4. 10. 1.4 - /SUCCESSFUL
Moves you forward to the next successfully compared result description.
22. 4. 10. 1.5 - /UNSUCCESSFUL
Moves you forward to the next unsuccessfully compared result description.
22. 4. 10. 1.6 - /UPDATED
Moves you forward to the next result description whose benchmark file has been updated.
22. 4. 10.2 - Example
DTM_REVIEW> NEXT 2
.
.
.
This example displays the result description that is two
positions ahead of the current result description.
22. 4.11 - PCA
Invokes the Analyzer of the VAX Performance and Coverage Analyzer
(PCA).
Format
PCA
22. 4.12 - PRINT
Selects one or more files for printing.
Format
PRINT [result-description-expression] [/qualifier...]
22. 4. 12.1 - Command Qualifiers
22. 4. 12. 1.1 - /BENCHMARK
Prints benchmark files from the specified result descriptions. The default is /RESULT.
22. 4. 12. 1.2 - /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.
22. 4. 12. 1.3 - /DIFFERENCES
Prints difference files from the specified result descriptions. The default is /RESULT.
22. 4. 12. 1.4 - /LOG
/LOG (D) /NOLOG Controls whether Digital Test Manager displays informational and success messages on the screen.
22. 4. 12. 1.5 - /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.
22. 4. 12. 1.6 - /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.
22. 4. 12. 1.7 - /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.
22. 4. 12. 1.8 - /RESULT
Prints the result file from the specified result descriptions. This is the default.
22. 4. 12. 1.9 - /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.
22. 4. 12. 1.10 - /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.
22. 4. 12. 1.11 - /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.
22. 4. 12. 1.12 - /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.
22. 4. 12.2 - 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.
22. 4.13 - SELECT
Moves you to the specified result description.
Format
SELECT result-description-name
22. 4. 13.1 - Example
DTM_REVIEW> SELECT MAIL_TEST Result Description MAIL_TEST Comparison Status : Unsuccessful This example displays the MAIL_TEST result description in a collection.
22. 4.14 - SHOW
Displays and describes output files for specified result
descriptions.
Format
SHOW [result-description-expression] [/qualifier...]
22. 4. 14.1 - Command Qualifiers
22. 4. 14. 1.1 - /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.
22. 4. 14. 1.2 - /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.
22. 4. 14. 1.3 - /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.
22. 4. 14. 1.4 - /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.
22. 4. 14. 1.5 - /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.
22. 4. 14. 1.6 - /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.
22. 4. 14. 1.7 - /OUTPUT
/OUTPUT[=file-specification] Sends the requested output to the specified file. The default is SYS$OUTPUT.
22. 4. 14. 1.8 - /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.
22. 4. 14. 1.9 - /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.
22. 4. 14. 1.10 - /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.
22. 4. 14. 1.11 - /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.
22. 4. 14. 1.12 - /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.
22. 4. 14.2 - 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.
22. 4.15 - SPAWN
Creates a subprocess of the current Digital Test Manager session.
Format
SPAWN [command] [/qualifier...]
22. 4. 15.1 - Command Qualifiers
22. 4. 15. 1.1 - /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.
22. 4. 15. 1.2 - /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.
22. 4. 15. 1.3 - /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.
22. 4. 15. 1.4 - /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.
22. 4. 15. 1.5 - /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.
22. 4. 15. 1.6 - /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.
22. 4. 15. 1.7 - /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.
22. 4. 15. 1.8 - /PROCESS
/PROCESS=subprocess-name Specifies the name of the subprocess to be created. The default is USERNAME_n (where n denotes a unique number).
22. 4. 15. 1.9 - /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.
22. 4. 15. 1.10 - /SYMBOLS
/SYMBOLS (D) /NOSYMBOLS Determines whether the system passes DCL global and local symbols to the subprocess.
22. 4. 15. 1.11 - /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.
22. 4. 15.2 - 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.
22. 4.16 - 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"
22. 4. 16.1 - Command Qualifiers
22. 4. 16. 1.1 - /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.
22. 4. 16. 1.2 - /LOG
/LOG (D) /NOLOG Controls whether Digital Test Manager displays informational and success messages on your screen.
22. 4. 16.2 - 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.
22.5 - Keypad
Review Subsystem Keypad +-------------+-------------+-------------+-------------+ | PF1 | PF2 | PF3 | PF4 | | GOLD | HELP KEYPAD | | | |[7m [0m|[7m HELP [0m|[7m [0m|[7m [0m| +-------------+-------------+-------------+-------------+ | 7 | 8 | 9 | - | | SHOW/DIF | SHOW/RES | SHOW/BEN | SHOW/SUM | |[7m PRINT/DIF [0m|[7m PRINT/RES [0m|[7m PRINT/BEN [0m|[7m [0m| +-------------+-------------+-------------+-------------+ | 4 | 5 | 6 | , | | PRINT/NOW | INSERT | UPDATE | SPAWN | |[7m [0m|[7m [0m|[7m [0m|[7m ATTACH/PAR [0m| +-------------+-------------+-------------+-------------+ | 1 | 2 | 3 | ENTER | | NEXT/UNSUCC | NEXT/NEW | NEXT/UPDATE | | |[7m BACK/UNSUCC [0m|[7m BACK/NEW [0m|[7m BACK/UPDATE [0m| | +-------------+-------------+-------------+ | | 0 | . | | | NEXT | FIRST | | |[7m BACK [0m|[7m LAST [0m|[7m [0m| +---------------------------+-------------+-------------+
| 23 - RUN |
Executes a collection interactively producing result files that
are subsequently compared with benchmark files.
Format
RUN collection-name [/qualifier...] "remark"
23.1 - Command Qualifiers
23. 1.1 - /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.
23. 1.2 - /LOG
/LOG (D) /NOLOG Controls whether Digital Test Manager displays informational and success messages on your screen.
23. 1.3 - /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.
23. 1.4 - /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.
23.2 - 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.
| 24 - SET |
24.1 - 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"]
24. 1.1 - Command Qualifier
24. 1. 1.1 - /LOG
/LOG (D) /NOLOG Controls whether Digital Test Manager displays informational and success messages on your screen.
24. 1.2 - 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.
24.2 - 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"
24. 2.1 - Command Qualifier
24. 2. 1.1 - /LOG
/LOG (D) /NOLOG Controls whether Digital Test Manager displays informational and success messages on your screen.
24. 2.2 - 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.
24.3 - LIBRARY
Selects an existing Digital Test Manager library.
Format
SET LIBRARY directory-specification [/qualifier...]
24. 3.1 - Command Qualifiers
24. 3. 1.1 - /LOG
/LOG (D) /NOLOG Controls whether Digital Test Manager displays informational and success messages on your screen.
24. 3. 1.2 - /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.
24. 3.2 - 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.
24.4 - 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"
24. 4.1 - Command Qualifier
24. 4. 1.1 - /LOG
/LOG (D) /NOLOG Controls whether Digital Test Manager displays informational and success messages on your screen.
24. 4.2 - 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.
24.5 - 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"
24. 5.1 - Command Qualifier
24. 5. 1.1 - /LOG
/LOG (D) /NOLOG Controls whether Digital Test Manager displays informational and success messages on your screen.
24. 5.2 - 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.
| 25 - SHOW |
25.1 - ALL
Displays a summary describing the current library.
Format
SHOW ALL [/qualifier]
25. 1.1 - Command Qualifier
25. 1. 1.1 - /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.
25. 1.2 - 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.
25.2 - BENCHMARK_DIRECTORY
Displays the directory specification for the current default
benchmark directory.
Format
SHOW BENCHMARK_DIRECTORY [/qualifier]
25. 2.1 - Command Qualifier
25. 2. 1.1 - /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.
25. 2.2 - Example
DTM> SHOW BENCHMARK_DIRECTORY
DUA0:[USER01.BMK] "Default benchmark library"
DTM>
This command displays the directory specification for the
current default benchmark directory.
25.3 - COLLECTION
Displays information about collections in the current Digital Test
Manager library.
Format
SHOW COLLECTION collection-expression [/qualifier...]
25. 3.1 - Command Qualifiers
25. 3. 1.1 - /BENCHMARK_DIRECTORY
Displays the directory specification of the benchmark directory used by this collection.
25. 3. 1.2 - /BRIEF
Displays the collection name. The default is /INTERMEDIATE.
25. 3. 1.3 - /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.
25. 3. 1.4 - /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.
25. 3. 1.5 - /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
25. 3. 1.6 - /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.
25. 3. 1.7 - /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.
25. 3.2 - 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.
25.4 - EPILOGUE
Displays the file specification for the default epilogue file for
collections.
Format
SHOW EPILOGUE [/qualifier]
25. 4.1 - Command Qualifier
25. 4. 1.1 - /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.
25. 4.2 - 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.
25.5 - GROUP
Displays the contents of one or more groups.
Format
SHOW GROUP group-expression [/qualifier...]
25. 5.1 - Command Qualifiers
25. 5. 1.1 - /BRIEF
Lists the group name only. You cannot specify both the /CONTENTS and /BRIEF qualifiers with the same command.
25. 5. 1.2 - /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.
25. 5. 1.3 - /FULL
Displays the same output as the /CONTENTS=ALL qualifier.
25. 5. 1.4 - /INTERMEDIATE
Lists the group name and any remark added during the creation, modification, or copying of the group. This is the default.
25. 5. 1.5 - /MEMBER
Lists the groups of which the specified groups are members.
25. 5. 1.6 - /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.
25. 5.2 - 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.
25.6 - HISTORY
Displays a chronological list of the transactions performed on
your Digital Test Manager library.
Format
SHOW HISTORY [object-expression] [/qualifier...]
25. 6.1 - Command Qualifiers
25. 6. 1.1 - /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.
25. 6. 1.2 - /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.
25. 6. 1.3 - /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.
25. 6. 1.4 - /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.
25. 6. 1.5 - /USER
/USER=user-name Lists in chronological order the library transactions performed by the specified user. You cannot use wildcards in user names.
25. 6.2 - 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.
25.7 - LIBRARY
Displays the directory specification of the current Digital Test
Manager library.
Format
SHOW LIBRARY [/qualifier]
25. 7.1 - Command Qualifier
25. 7. 1.1 - /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.
25. 7.2 - Example
DTM> SHOW LIBRARY Your Digital Test Manager library is DUA0:[USER01.DTMLIB] DTM> This example displays your current Digital Test Manager library.
25.8 - PROLOGUE
Displays the file specification of the default prologue file for
collections.
Format
SHOW PROLOGUE [/qualifier]
25. 8.1 - Command Qualifier
25. 8. 1.1 - /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.
25. 8.2 - 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.
25.9 - TEMPLATE_DIRECTORY
Displays the directory specification for the default directory
that contains the template files.
Format
SHOW TEMPLATE_DIRECTORY [/qualifier]
25. 9.1 - Command Qualifier
25. 9. 1.1 - /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.
25. 9.2 - Example
DTM> SHOW TEMPLATE_DIRECTORY
DUA0:[USER01.TEMPLATE] "Default template library"
DTM>
This example displays the directory specification for the
current default template directory.
25.10 - TEST_DESCRIPTION
Displays the files and groups associated with one or more test
descriptions.
Format
SHOW TEST_DESCRIPTION [test-group-expression] [/qualifier...]
25. 10.1 - Restrictions
o The /COMMAND qualifier applies to DECwindows tests only.
o The /FILTER qualifier applies to noninteractive and terminal
tests only.
25. 10.2 - Command Qualifiers
25. 10. 2.1 - /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
25. 10. 2.2 - /BRIEF
Displays the test name.
25. 10. 2.3 - /COMMAND
Displays the command that is used to begin recording and executing of the test. This qualifier applies to DECwindows tests only.
25. 10. 2.4 - /COMPARISON_TYPE
Displays the comparison type associated with the specified test description.
25. 10. 2.5 - /EPILOGUE
Displays the file specification for the epilogue file associated with the specified test description.
25. 10. 2.6 - /FILTER
Displays the names for all filters associated with the specified test description.
25. 10. 2.7 - /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
25. 10. 2.8 - /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.
25. 10. 2.9 - /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.
25. 10. 2.10 - /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.
25. 10. 2.11 - /PROLOGUE
Displays the file specification for the prologue file associated with the specified test description.
25. 10. 2.12 - /REMARK
Displays the remark associated with the test description.
25. 10. 2.13 - /TEMPLATE
Displays the file specification for the template associated with the specified test description.
25. 10. 2.14 - /TYPE
Displays the type of the specified test description-NONINTERACTIVE, INTERACTIVE, or DECWINDOWS.
25. 10. 2.15 - /VARIABLE
Displays the names and values for all variables associated with the test description.
25. 10.3 - Parameter Qualifiers
25. 10. 3.1 - /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.
25. 10. 3.2 - /TEST_DESCRIPTION
Identifies the immediately preceding item in the parameter as a test expression. This is the default.
25. 10.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.
25.11 - VARIABLE
Displays information about the specified variables.
Format
SHOW VARIABLE variable-expression [/qualifier...]
25. 11.1 - Command Qualifiers
25. 11. 1.1 - /BRIEF
Displays the variable name only.
25. 11. 1.2 - /FULL
Displays the name, value, scope, usage, and remark for the variable and lists the tests with which the variable is associated.
25. 11. 1.3 - /INTERMEDIATE
Displays the name, value, and remark for the variable. This is the default.
25. 11. 1.4 - /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.
25. 11. 1.5 - /REMARK
Displays the remark associated with the variable.
25. 11. 1.6 - /SCOPE
Displays the scope of the variable. The scope can be either global or local.
25. 11. 1.7 - /TEST_DESCRIPTION
Lists the test descriptions with which the variable is associated.
25. 11. 1.8 - /TYPE
Displays the type of variable-STRING or NUMERIC.
25. 11. 1.9 - /USAGE
Displays the use of the variable. The use can be either as a symbol or as a logical.
25. 11. 1.10 - /VALUE
Displays the variable's default value. If no value has been supplied, the null value is displayed.
25. 11.2 - 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.
25.12 - VERSION
Displays the version number for Digital Test Manager currently in use
on the system.
Format
SHOW VERSION [/qualifier]
25. 12.1 - Command Qualifier
25. 12. 1.1 - /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.
25. 12.2 - Example
DTM> SHOW VERSION Compaq Digital Test Manager Version 4.0 DTM> This example displays the version number of Digital Test Manager.
| 26 - SPAWN |
Creates a subprocess from the current Digital Test Manager session-the
parent process.
Format
SPAWN [command] [/qualifier...]
26.1 - Command Qualifiers
26. 1.1 - /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.
26. 1.2 - /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.
26. 1.3 - /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.
26. 1.4 - /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.
26. 1.5 - /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.
26. 1.6 - /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.
26. 1.7 - /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.
26. 1.8 - /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).
26. 1.9 - /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.
26. 1.10 - /SYMBOLS
/SYMBOLS (D) /NOSYMBOLS Determines whether the system passes DCL global and local symbols to the subprocess.
26. 1.11 - /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.
26.2 - 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.
| 27 - STOP |
Stops a collection that has been submitted to a batch queue.
Format
STOP collection-name [/qualifier...] "remark"
27.1 - Command Qualifiers
27. 1.1 - /CONFIRM
/CONFIRM /NOCONFIRM (D) Controls whether Digital Test Manager prompts you to confirm that you want to stop the collection.
27. 1.2 - /LOG
/LOG (D) /NOLOG Controls whether Digital Test Manager displays informational and success messages on your screen.
27.2 - 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.
| 28 - SUBMIT |
Executes a collection in batch producing result files that are
subsequently compared with benchmark files.
Format
SUBMIT collection-name [/qualifier...] "remark"
28.1 - Restrictions
o You can submit collections that contain DECwindows tests
but you must be logged into the DECwindows environment and
initialize it for testing.
28.2 - Command Qualifiers
28. 2.1 - /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.
28. 2.2 - /KEEP
/KEEP (D) /NOKEEP Controls whether the log file is deleted after is it printed.
28. 2.3 - /LOG
/LOG (D) /NOLOG Controls whether Digital Test Manager displays informational and success messages on your screen.
28.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.
28.4 - 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.
| 29 - VERIFY |
Evaluates the integrity of the current Digital Test Manager library
and its collections.
Format
VERIFY [/qualifier...] "remark"
29.1 - Command Qualifiers
29. 1.1 - /LOG
/LOG (D) /NOLOG Controls whether Digital Test Manager displays informational and success messages on your screen.
29. 1.2 - /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.
29. 1.3 - /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.
29.2 - 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.
| 30 - 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 3.9 would be located
in SYS$HELP:DTM039.RELEASE_NOTES.
To list all the available Digital Test Manager release notes,
specify the following DCL command:
$ DIRECTORY SYS$HELP:DTM*.RELEASE_NOTES
| 31 - 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
| 32 - 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 Compaq 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.
32.1 - 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
Compaq 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=" "
32.2 - 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
32.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
32.4 - Examples
Example 1: Simple Use of procedure global_replace
The following example assumes that the disks are named UDISK<n>
where <n> 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.
|
|
