{
{ PURPOSE:
{   This module contains the command language and file system test harnesses.
{   The command language and file system may be run as separate test harnesses
{   or together as one test harness.
{
{ Listed below are commands for building and running the test harness.  These
{ commands are currently available in .rrp.test_harness.command_library.
{   1. CHECK_STUBBED_PROCEDURES
{      This command will generate a list of latest modification dates and times
{      of the xref decks in .intve.os.source_library for each stubbed procedure
{      in the test harness.  It can also compare this new list against a
{      previous one and list the stubbed procedure names whose xref deck
{      modification date or time has changed.
{      Parameters:
{        old_file                :file containing stubbed procedure names with
{                                 their xref deck modification date and time.
{                                 The new list of stubbed procedure names with
{                                 their latest xref deck modification date and
{                                 time is compared with this file.  If the file
{                                 is omitted no comparison is made.
{        new_file                :file that will contain the stubbed procedure
{                                 names with their latest xref deck modification
{                                 date and time.
{        modification_file       :file that will contain the stubbed procedure
{                                 names that have a new xref deck modification
{                                 date or time as a result from the above
{                                 comparison.
{        found_new_modifications :indicates if a new xref deck modification date
{                                 or time has been found for a stubbed procedure
{                                 as a result from the above comparison.
{   2. BUILD_NEW_TEST_HARNESS
{      This command will submit a batch job to build the appropriate test
{      harness.
{      Paramters:
{        kind                       :type of test harness to be built.
{        build_level                :build level the test harness is to be
{                                    compiled at.
{        catalog                    :catalog that will contain the test harness
{                                    library, binaries, and listing library.
{        debug                      :indicates if the test harness is to be
{                                    compiled with debug information.
{        test_tool_build_level      :build level of the test tool library used
{                                    to satisfy external references.
{        check_stubbed_procedures   :indicates whether to execute the
{                                    CHECK_STUBBED_PROCEDURES command and to
{                                    keep building the test harness if new xref
{                                    deck modifications are found for the test
{                                    harness stubbed procedures.
{        old_stubbed_procedure_file :defined in CHECK_STUBBED_PROCEDURES
{                                    command. If check_stubbed_procedures
{                                    parameter is set to 'ignore' this parameter
{                                    is ignored.
{        new_stubbed_procedure_file :defined in CHECK_STUBBED_PROCEDURES
{                                    command. If check_stubbed_procedures
{                                    parameter is set to 'ignore' this parameter
{                                    is ignored.
{        modification_file          :defined in CHECK_STUBBED_PROCEDURES
{                                    command. If check stubbed_procedures
{                                    parameter is set to 'ignore' this parameter
{                                    is ignored.
{   3. BIND_TEST_HARNESS
{      This command will create a bound version of the test harness.
{      Parameters:
{        bound_library           :object library that will contain the test
{                                 harness bound module.
{        library                 :list of object libraries that will comprise
{                                 the test harness bound module.
{        kind                    :type of test harness.
{        retain                  :entry point names to be retained in the test
{                                 harness bound module.
{        enable_test_environment :indicates if libraries for
{                                 create_test_environment should be added to
{                                 test harness bound module.
{        feature_test_binary     :object library containing the feature test
{                                 binaries for create_test_environment.
{                                 If enable_test_environment parameter is
{                                 set to 'false' this parameter is ignored.
{   4. CREATE_TEST_HARNESS_PGM_DESC
{      This command will create a program description that will execute the
{      appropriate test harness.
{      Pararmeters:
{        pgm_desc_library         :object library that will contain the test
{                                  harness program description.
{        pgm_desc_name            :list of names defined for the test harness
{                                  program description.
{        library                  :list of object libraries that will be added to
{                                  the program library list when the test harness
{                                  harness is executed.
{        bound                    :indicates if the test harness is bound.
{        kind                     :type of test harness.
{        termination_error_level  :indicates the termination error level for
{                                  running the test harness.
{        enable_test_environment  :indicates if create_test_environment will
{                                  be enabled for the test harness.
{        feature_test_binary      :object_library containing the feature
{                                  test binaries for create_test_environment.
{                                  If enable_test_environment parameter is
{                                  set to 'false' this parameter is ignored.
{   5. ESTABLISH_SCL_ENVIRONMENT
{      This command will create the necessary environment needed before the SCL
{      test harness is run.
{      Parameters:
{        message_template_library :list of object libraries containing message
{                                  modules to be added to
{                                  $local.osf$command_library.
{   6. ESTABLISH_FS_ENVIRONMENT
{      This command will create the necessary environment needed before the FS
{      test harness is run.
{   7. EXECUTE_TEST_HARNESS
{      This command will create the necessary test harness environment by
{      executing command(s) ESTABLISH_SCL_ENVIRONMENT and/or
{      ESTABLISH_FS_ENVIRONMENT.  It will the execute the appropriate test
{      harness by using a supplied program description or by creating an EXET
{      command.
{      Parameters:
{        library                  :list of libraries to be added to program
{                                  library list via the EXET command.  This
{                                  parameter is ignored if a program description
{                                  is supplied.
{        pgm_desc_library         :object library containing a program
{                                  description to execute the test harness.
{        pgm_desc_name            :name of the program description to execute
{                                  the test harness.
{        kind                     :type of test harness.  This parameter is
{                                  ignored if a program description is supplied.
{        bound                    :indicates if the test harness is bound.  This
{                                  parameter is ignored if a program description
{                                  is supplied.
{        termination_error_level  :indicates the termination error level for
{                                  running the test harness.
{        message_template_library :defined in ESTABLISH_SCL_ENVIRONMENT command.
{                                  This parameter is ignored if a program
{                                  description is supplied or the parameter kind
{                                  is 'fs'.
{        enable_test_environment  :indicates if create_test_environment should
{                                  be enabled for the test harness.  This
{                                  parameter is ignored if a program description
{                                  is supplied.
{        feature_test_binary      :object_library containing the feature
{                                  test binaries for create_test_environment.
{                                  It will be added to the program library list
{                                  via the EXET command.  This parameter is
{                                  ignored is a program description is supplied
{                                  or enable_test_environment parameter is set
{                                  to 'false'.
{
{ Listed below is information regarding the different test harnesses.  To the
{ left of the information is a table indicating the test harness(es) to which
{ the information pertains. Any parameters referred to below are in relation
{ to an EXET command or a program description used to execute the test harness.
{
{ |SCL| FS|FS_SCL| BUILDING THE TEST HARNESS
{ |   |   |      | 1. Test harness procedure name to be specified on the
{ |   |   |      |    starting_procedure parameter
{ | * |   |  *   |    a. clp$test_harness.
{ |   | * |      |    b. fsp$test_harness.
{ |   |   |      | 2. Using an ubound version of the test harness
{ | * |   |  *   |    a. All libraries that are to be used including the test
{ |   |   |      |       harness should be specified in the library parameter.
{ |   |   |      |       This will eliminate any problems with multiple
{ |   |   |      |       executions of the same entry point.  It allows the
{ |   |   |      |       capability to reload the entry point.  The libraries
{ |   |   |      |       could also be put into the job library list.
{ |   |   |      | 3. Using a bound version of the test harness
{ | * |   |  *   |    a. All libraries that are to be used must be bound
{ |   |   |      |       together with the test harness library.
{ | * |   |  *   |    b. All entry point names that will be executed more than
{ |   |   |      |       once must be retained on the bound module.
{ | * |   |  *   |    c. If TASK/TASKEND statements will be executed, the entry
{ |   |   |      |       point name clp$task_taskend must be retained on the
{ |   |   |      |       bound module.
{ | * |   |  *   |    d. Omit all other non-retained entry points.
{ | * |   |  *   |    e. The bound library should be specified in the library
{ |   |   |      |       parameter.
{ | * |   |  *   |    f. Always execute the bound version with the debug_mode
{ |   |   |      |       parameter set to ON!  This will eliminate problems with
{ |   |   |      |       multiple executions of the same entry point because
{ |   |   |      |       entry points cannot be reloaded.  Some entry points such
{ |   |   |      |       as the editor will be affected by this since it is not
{ |   |   |      |       reloaded after the first time it is executed.
{ |   | * |  *   | 4. All AM, BAM, FM, PF, FS and test utility code are required
{ |   |   |      |    unmodified.
{ |   | * |  *   | 5. To make amp$return work, take out ring checking of
{ |   |   |      |    fmp$return_file, fmm$job_file_mgr.
{ |   | * |  *   | 6. Add the test tools library to the program library list.
{ |   |   |      |   (normally resides on .testve.test_tools.build_xxxxx.
{ |   |   |      |    ttf$test_tool_library)
{ |   | * |  *   | 7. The loadmap should be checked for dangerous references to
{ |   |   |      |    TASK_SERVICES.
{ |   | * |  *   | 8. Suggested enhancements:
{ |   | * |  *   |    a. Enforcement of protocol on mmp$lock, mmp$unlock
{ |   |   |      | 9. Examples
{ |   |   |      |    a. Executing an unbound version of the test harness
{ | * | * |      |       1. EXET library=(unbound_test_harness_library, ..
{ |   |   |      |               my_first_library, my_second_library) ..
{ |   |   |      |               starting_procedure=clp$test_harness
{ |   |   |  *   |       2. CREOL
{ |   |   |      |           addm library=(unbound_test_harness_library)
{ |   |   |      |           sater library=.testve.test_tools.build_xxxxx..
{ |   |   |      |                 .ttf$test_tool_library
{ |   |   |      |           genl library=unbound_test_harness_library
{ |   |   |      |         QUIT
{ |   |   |      |         EXET library=unbound_test_harness_library ..
{ |   |   |      |              sp=fsp$test_harness ..
{ |   |   |      |              termination_error_level=fatal
{ |   |   |      |    b. Executing a bound version of the test harness
{ | * |   |  *   |       1.CREOL
{ |   |   |      |           addm library=(unbound_test_harness_library, ..
{ |   |   |      |                my_first_library, my_second_library)
{ |   |   |      |           genl library=all_libraries
{ |   |   |      |           crem name=bound component=all_libraries ..
{ |   |   |      |           starting_procedure=clp$test_harness ..
{ |   |   |      |           retain=(clp$task_taskend, my_first_command, ..
{ |   |   |      |                  my_second_command)
{ |   |   |      |           chama name=bound omit_non_retained_entry_points=yes
{ |   |   |      |           genl library=bound_test_harness_library
{ |   |   |      |         QUIT
{ |   |   |      |         EXET library=bound_test_harness_library ..
{ |   |   |      |              starting_procedure=clp$test_harness ..
{ |   |   |      |              debug_mode=on
{ |   |   |      |
{ |   |   |      | RUNNING THE TEST HARNESS
{ | * | * |  *   | 1. The test harness must be in bound version to use the
{ |   |   |      |    debugger.
{ | * | * |  *   | 2. The unbound version of the test harness may be used
{ |   |   |      |    with measure_program_execution.
{ |   |   |      |    measure_program_execution
{ |   |   |      |      set_program_description target_text=test_harness_..
{ |   |   |      |        library sp=test_harness_starting_procedure
{ |   |   |      |      execute_instrumented_task
{ |   |   |      |        " Enter commands as you would normally
{ |   |   |      |        " Enter command to leave test harness
{ |   |   |      |      display_program_profile puc=local n=200 ..
{ |   |   |      |        output=output_file
{ |   |   |      |    quit
{ | * | * |  *   | 3. Some stubbed procedures used for multiple tasks will
{ |   |   |      |    display a message to the job log indicating thay are
{ |   |   |      |    being executed. A couple examples are pmp$execute and
{ |   |   |      |    pmp$abort.
{ |   |   |      | 4. The following represent known restrictions in this
{ |   |   |      |    environment:
{ | * | * |  *   |    a. no tape files,
{ |   |   |  *   |    b. no implicit attaches,
{ | * |   |  *   |    c. all files are treated as unconnected,
{ | * |   |  *   |    d. all open positions specified on commands are ignored.
{ | * |   |  *   | 5. A library containing a message template module should be
{ |   |   |      |    added to the command list. ESTABLISH_SCL_ENVIRONMENT
{ |   |   |      |    command does this.
{ | * |   |  *   | 6. Only the starting procedure parameter of an EXET command
{ |   |   |      |    or program description is processed. The starting
{ |   |   |      |    procedure must be in a library specified in the library
{ |   |   |      |    parameter at the point of excuting the test harness.
{ | * |   |  *   | 7. If executing a command as object_library.entry point or
{ |   |   |      |    object_library.program_description, the entry point to be
{ |   |   |      |    executed must be in a library specified in the library
{ |   |   |      |    parameter at the point of executing the test harness.
{ | * |   |  *   | 8. Execution of an object file as a command will not work
{ |   |   |      |    because the starting procedure is not determined.
{ |   | * |   *  | 9. The file system environment must be cleaned up before
{ |   |   |      |    executing the test harness.  ESTABLISH_FS_ENVIRONMENT
{ |   |   |      |    command does this.
{ | * | * |   *  | 10.If executing the test harness with enable_test_environment
{ |   |   |      |    set to 'true' then termination_error_level must be set
{ |   |   |      |    to 'fatal'.
{ |   |   |      |    The command library .rrp.test_harness.command_library
{ |   |   |      |    must be put into the command list.  The command for
{ |   |   |      |    create_test_environment is th_create_test_environment.
{ |   |   |      |    And the command for run_test is th_run_test.
{ |   |   |      |    The libraries .testve.test_tools.bound_product and
{ |   |   |      |    $system.osf$site_command_library are accessed.  If
{ |   |   |      |    feature_test_binary is set to 'current_build' a file
{ |   |   |      |    called $local.osf$f_test_binaries is created and accessed.
{ |   | * |      | 11.EXET commands, TASK/TASKEND statements, and any other type
{ |   |   |      |    of execution of binaries will execute in the real system.
{ |   | * |   *  | 12.For each test harness file or catalog created there is an
{ |   |   |      |    associated REAL file system file created. The first real
{ |   |   |      |    file is called $local.JJJ1, the second JJJ2, and so on.
{ |   |   |      |    This is a segment access file, and may be inspected with
{ |   |   |      |    the display_file command.  (Be sure to give byte_address
{ |   |   |      |    on the display_file).
{ |   | * |   *  | 13.To use permanent files do:
{ |   |   |      |      recover_files
{ |   |   |      |      define_master_catalog $user
{ |   |   |      |    To run through pf recovery do
{ |   |   |      |      recover_files
{ |   | * |      | 14.Always specify a LFN on all attach_file, and create_file
{ |   |   |      |    requests.  On detach_file be sure to specify $Local.file
{ |   |   |      |    name.  In general do not use working catalog, nor let the
{ |   |   |      |    lfn default.
{ |   | * |   *  | 15.To attempt job recovery do:
{ |   |   |      |      Create the permanent file base as above
{ |   |   |      |      recover_files recover_files=true
{ |   |   |      |      recover_job_files (for each job)
{ |   | * |   *  | 16.Bringing files into the environment - A terrible mess
{ |   |   |      |    colt file
{ |   |   |      |      put at least 100 bytes into the file
{ |   |   |      |    pause break
{ |   |   |      |    use disf to see which fake file to use
{ |   |   |      |    copf your real file $Local.jjjx
{ |   |   |      |    resc
{ |   |   |      |    chafa file to the needed file attributes
{ |   |   |      |    fc=object and fs=library for command libraries
{ |   |   |      |
{ |   |   |      | ADDITIONAL TEST HARNESS COMMANDS AND FUNCTIONS
{ |   |   |      | 1. The test harness commands and functions can be displayed
{ |   |   |      |    with the DISCLE command.  A list is shown below:
{ |   | * |   *  |    command (attach_file, attf)
{ |   | * |   *  |    command (change_catalog_entry, chace)
{ |   | * |   *  |    command (change_family_name, chafn)
{ |   | * |   *  |    command (change_file_attributes, change_file_attribute,
{ |   |   |      |             chafa)
{ |   | * |   *  |    command (compare_file, comf)
{ |   | * |   *  |    command (copy_file, copf)
{ |   | * |   *  |    command (create_catalog, crec)
{ |   | * |   *  |    command (create_catalog_permit, crecp)
{ |   | * |   *  |    command (create_file, cref)
{ |   | * |   *  |    command (create_file_permit, crefp)
{ |   | * |   *  |    command (delete_catalog, delc)
{ |   | * |   *  |    command (delete_catalog_permit, delcp)
{ |   | * |   *  |    command (delete_file, delf)
{ |   | * |   *  |    command (delete_file_permit, delfp)
{ |   | * |   *  |    command (detach_file, detach_files, detf)
{ |   | * |   *  |    command (display_catalog, disc)
{ |   | * |   *  |    command (display_catalog_entry, disce)
{ |   | * |   *  |    command (display_file_attributes, display_file_attribute,
{ |   |   |      |             disfa)
{ |   | * |   *  |    command (rewind_file, rewind_files, rewf)
{ |   | * |   *  |    command (set_file_attributes, set_file_attribute, setfa)
{ |   | * |   *  |    command (set_job_recovery_test, setjrt)
{ |   | * |   *  |    command (known_point, kp)
{ |   | * |      |    command (bap$task_termination_cleanup, task_termination)
{ |   | * |      |    command (job_exit)
{ |   | * |   *  |    command (define_master_catalog, defmc)
{ |   | * |   *  |    command (purge_master_catalog, purmc)
{ |   | * |   *  |    command (backup_permanent_files, backup_permanent_file,
{ |   |   |      |             bacpf)
{ |   | * |   *  |    command (restore_permanent_files, restore_permanent_file,
{ |   |   |      |             respf)
{ |   | * |   *  |    command recover_job_files
{ |   | * |   *  |    command recover_files
{ |   | * |   *  |    command (system_test_utility, systu)
{ |   | * |   *  |    command (set_administator_status, setas)
{ |   | * |      |    command (set_job_number, setjn)
{ |   | * |      |    command (set_task_number, settn)
{ |   | * |   *  |    command (set_user_id, setui)
{ |   | * |      |    command (quit, qui)
{ |   | * |   *  |    command (validate_catalog, valc)
{ |   | * |   *  |    function $file
{ |   | * |   *  |    function ($real_file_name, $rfn)
{ |   | * |  *   | 2. Test harness command known_point.
{ |   |   |      |    This command may be used to force a break to look at task
{ |   |   |      |    file tables or any of the job tables. When entering the
{ |   |   |      |    debugger do:
{ |   |   |      |      setb kp m=clm$test_harness p=known_point bo=xx(16)
{ |   |   |      |    When you desire to inspect a table do a set_job_number to
{ |   |   |      |    the current job, this will flush the tables to the
{ |   |   |      |    'multiple_job_table'.  You may then do kp and display the
{ |   |   |      |    table from the multiple job table.
{ |   | * |  *   | 3. Test harness command set_user_id.
{ |   |   |      |    Multiple users may be defined, to run under a different
{ |   |   |      |    user.  '$USER' however will always get your original user
{ |   |   |      |    name.  When you change user identification you should
{ |   |   |      |    probably also change jobs using set_job_number.  If you
{ |   |   |      |    don't do this you will inherit any authority for any
{ |   |   |      |    catalog in the queued catalog table.  This will make you
{ |   |   |      |    appear as owner for the original user as well as the
{ |   |   |      |    new user.
{ |   | * |      | 4. Test harness commands set_job_number and set_task_number.
{ |   |   |      |    Up to  5 jobs and tasks are supported, however they do
{ |   |   |      |    share the same heap.  Be careful - once a job is
{ |   |   |      |    terminated (via job_exit) or a task (via
{ |   |   |      |    bap$task_termination_cleanup) that job_number or
{ |   |   |      |    task_number should NOT be reused.
{
