gtpp1m0dProgram Development Support Reference

Trace Input

The following section discusses the various types of input you can use when running the PTV utility.

Test Unit Tape (TUT)

The preliminary input to the PTV utility is the test unit tape generated by the system test compiler (STC). A test unit tape (TUT) is a tape file consisting of 1 or more test units used to test application programs. This tape is created by the STC from the RUNID test units that STC processed as input. Each test unit contains a RUNID to identify the test unit, data records to be loaded, and input messages to be processed.

The primary purpose of this tape is to supply input to the program test vehicle (PTV) utility. The PTV utility uses the TUT solely as input. The TUT is not modified after it is created.

Test Unit Tape (TUT) Contents

The RUNID card is written to the TUT in card-image format to identify the test unit. After the RUNID card is written to the tape, there may be dump options and terminal simulation records written in card-image format. Finally, the existing data records are written to the tape. The records are either called from the standard data/message file or created by the data generation portion of the STC.

The input messages are last in a test unit. The messages are created by the data generation portion of the STC.

Phase 3 (Package Test) Mode

To run the PTV utility in the Phase 3 (package test) mode, provide the following input. See Program Test Vehicle (PTV) Modes for more information about the Phase 3 (package test) mode.

  1. RUNID record

    This is an 80-character card-image record.

  2. Dump option and terminal simulation records, if there are any

    These are 80-character card-image records.

  3. 9s record

    This 20-byte record indicates the end of the Dump option and Terminal Simulation records in this test unit.

  4. Data records, if there are any

    These are usually 941-, 1615-, or 4655-byte records. The first 560 bytes of the record are used as a prefix to the actual data record. This prefix contains bit settings to indicate record type and ordinal number for file address calculation in the record. The format of this prefix is the same as the format of the SDMF data record prefix. See the SDFPF data macro.

  5. 9s record

    This 20-byte record indicates the end of the data in this test unit.

  6. Message records, if there are any

    The messages are blocked in variable size blocks. The maximum record size depends on the maximum 3270 message length as defined in the system initialization program (SIP) deck (NETWK statement M3270 parameters).

  7. Two 9s records

    These two 20-byte records indicate the end of the blocked messages in this test unit.

    The previous steps are repeated for each test unit.

  8. End STC record

    This 80-byte card-image record signifies the end of the TUT.

System Test Vehicle (STV) Mode

To run the PTV utility in STV mode, provide the following input. See Program Test Vehicle (PTV) Modes for more information about the STV mode.

  1. RUNID record

    This is an 80-character card-image record.

  2. Two 9s records

    These two 20-byte records indicate that the tape does not contain any data.

  3. Message records

    The messages are blocked in variable size blocks. The maximum record size depends on the maximum 3270 message length as defined in the system initialization program (SIP) deck (NETWK statement m3270 parameter).

  4. Two 9s records

    These two 20-byte records indicate the end of the blocked messages in this tape.

  5. End STC record

    This 80-byte card image record indicates the end of the TUT.

Pilot Tape

A pilot system tape is similar in format to a test unit tape (TUT) but can contain only data records; no programs or messages are on pilot tapes. A pilot system tape is generated by the STC and can contain more than one pilot system or set of data records. Each pilot system on the pilot tape is preceded by a RUNID record that contains PILOT in position 8-12 and the identification number of the pilot system.

You can have a pilot system loaded for a unit or package test. STC records the request on the TUT and the PTV utility will load the pilot according to the information specified on the RUNID record. See Pilot Tape Generation for more information about STC generation of pilot tapes.

Online Disk Packs

The online disk packs are created by the system loader. They contain the control program, IPL record and bootstrap, keypoints, restart segments, required application programs, and predefined data records.

The PTV utility must be loaded to the online file modules before running PTV. Data records can be obtained from a pilot system, if specified; application programs are obtained from the object library. These packs are formatted according to the structure created by the system allocator and the system configuration (SYSCON) macro.

Test units can make use of any data in the online system or can overlay the data with the TUT input using the online, allocated locations. In either case, the PTV utility always restores the originals at the end of the run.

PTV Control Records

The following section discusses:

Test Unit Identification Record (RUNID)

The RUNID record defines the start of a test unit, the programs to be tested, testing conditions, and any test options. See Table 2 for the required RUNID format. The following information is specified on the RUNID record.

Test Unit Identifier

Five characters in position 8-12 that identify the test unit. If the RUNID record identifies a pilot system, the characters PILOT are entered in position 8-12.

Database Restore Indicator

A blank (do not restore) or a D (restore database at beginning of test unit) in position 13. The option is whether to restore the database at the start of the test unit. Database restore is always active for all test units on the TUT.

Pilot System Identification

A nonblank character is required in position 14 if a pilot tape is to be loaded. If position 14 is not coded, a pilot tape is not loaded. If a previous test unit loads a pilot tape, the pilot tape retains all modifications made to it unless the database restore option is active.

User of Pilot Tape

A blank in position 15 indicates the pilot tape for the subsystem user (SSU) pilot tape is loaded. If data is entered in position 15, the basic subsystem (BSS) pilot tape is loaded.

Global Storage Load

Position 16 is a single digit (1-9), which specifies the mode of global storage load.

Screen Reset Indicator

When output messages for a 3270 are postprocessed by the offline diagnostic output formatter (DOF), an output message may lock the keyboard. When this occurs, the DOF expects an additional message to unlock the keyboard. For more information about keyboard lock and how to code position 17 in the RUNID, see Keyboard Lock.

Message Input Mode

Position 25 is either A for asynchronous mode, or B for burst mode.

Number of Messages in System

Position 26 is the number (1-9) of messages to be maintained in the system if position 25 specified A, or supplied in each burst if position 25 is B.

Online Terminal Use

Position 27 specifies L for live test or is left blank. L permits the use of online terminals during unit test and while testing in live or phase 3 (package test) modes.

Running State

Position 28 is either blank for NORM state, 1 for 1052 state, 2 for CRAS, or 4 for MESW.

User Comments

User comments are entered in position 35-80. It is possible to have multiple RUNID records for each input tape. In system test vehicle (STV) mode, the RUNID record is the first record of the tape and serves as a tape identification record. You can only have 1 RUNID record for each input tape while using STV mode. The characters, RUNID (position 2-6), are the minimal required information for the RUNID record.

Position 17 can be used to specify the screen reset indicator. Positions 35-80 are reserved for comments. All other positions are reserved for future use by the PTV utility. All other options are specified through commands. See TPF Operations for more information about the PTV commands. The RUNID record is immediately followed by message records.

Terminal Simulation Options

If you require the input and output for certain terminals to be printed in simulated terminal format in addition to the normal output printed by the DOF, terminal simulation records must be included in the test unit.

When running the PTV utility in system test vehicle (STV) mode, the terminal tables assembled in the BMP0 (STPP) segment are used to control simulation.

See Diagnostic Output Formatter (DOF) Online and Offline Utility for more information about the diagnostic output formatter (DOF). See Table 3 for the required format.

The following section explains the types of information entered on the terminal simulation record.

Note:
You must provide a separate terminal simulation record for each type of device in a given test unit.

Device Type

There are 11 device types that can be specified in position 2-7.

Device Type
Description

 CRTs 
Display device (2915 or 4505)

 1977 
1977 hardcopy

 1980 
1980-21

 1984 
1980-24 hardcopy

 3277-1 
3277 Model 1 (480 character) display device

 3277-2 
3277 Model 2 (1920 character) display device plus 3284-3 printer

 328X-1 
3284 Model 1 (480 character) or 3286 Model 1 (1920 character) print, if attached

 328X-2 
3284 Model 2 (1920 character) or 3286 Model 2 (1920 character) printer, if attached.

Device Address

The address of the device to be simulated is specified in position 16-80. The address can be specified as follows.

Address
Description

 LNIATA 
The identify of a display device or 1977, 1980-021, or 1980-024 terminals.

Each field contains the line number (LN), interchange address (IA), and terminal address (TA), each expressed as 2 hexadecimal digits. Each 6-column field, except the last, is followed by a comma. A maximum of 8 terminals can be specified for each device type.

 LNIATA(CD) 
The identity of a 3277 Model 1 or 2, a 3284 Model 1 or 2, or a 3286 Model 1 or 2.

Each 10-column field contains the:

The control unit and device address are separated from the LNIATA by the delimiters shown; for example, ( and ).

Each address is expressed as 2 hexadecimal digits except the control unit and device address, which are each 1 hexadecimal digit. A maximum of 6 terminals can be specified for each type of device.

Note:
These LNIATA(CD) terminal addresses are only used for non-SDLC terminals.

 LEID 
The logical endpoint identifier is the address of a terminal attached through the network extension facility (NEF).

The LEID is 3 bytes long and represents the endpoint, which is either the terminal or the function associated with that terminal, which remains with the terminal or the function regardless of a change in the network physical addressing structure.

Dump Options (DUMP)

One or more DUMP records can be included when you require additional output to supplement RTT output. A test unit can contain multiple dump option records with the following restrictions:

The contents of DUMP records are analyzed by the PTV utility at the beginning of each test unit. The PTV utility contains 2 tables, one with an entry for each system macro, and the other with space for as many as 50 application program segment 4-byte names. As each DUMP record is read, an indication of the option code is entered in the locations in the macro table corresponding to the macro or macro group in the record. A pointer to the first available field in the program name table is also placed in each macro table entry. The program segment names are then copied from the DUMP record image into successive program name table fields.

Once the DUMP record information has been stored during PTV initialization, it remains dormant until the RTT utility gets control at each macro time during test processing. On each such occasion, the RTT utility determines from its indicators in the ECB whether such output is required for the macro just issued. If both conditions are satisfied, the requested RTT output is generated, and the PTV macro and program tables are examined to determine whether additional output is required for the particular macro and program.

The dump option code, macro identifier, and program segment name are coded by you, copied to the test unit tape by the STC, and processed by the PTV utility during the test. See Dump Options (DUMP) for the required format for DUMP input.

The following section explains the information you can enter in the DUMP record.

Input Messages

The STC data generation facility is used to generate the input messages that are activated for the test. They are identified in the input stream by the MSG record, followed by the data generation detail records; this group must be the last input to the STC for a test unit. The PTV utility stores the messages and activates them in sequence using the procedure required for the type of test.

Required Input Sequence

The PTV utility expects to receive the following user-defined records input in this sequence for each type of test:

Sample Job Control Language (JCL) for the Test Unit Tape (TUT)

A sample of job control language (JCL) that can be used to create a test unit tape (TUT) for the STV or phase 3 (package test) mode of testing is detailed in Figure 2.

Figure 2. Sample JCL for the TUT for Phase 3 (Package Test)

//STC  EXEC   PGM=STC,REGION=400K,PARM='SALVER=24,SALSIZ=125000'
//STEPLIB   DD  DSN=LINKLIB,DISP=SHR
//STCDD     DD  DSN=OBJECTLIB.OB,DISP=SHR
//SALTB     DD  DSN=SALTABLE,DISP=SHR
//SYSPRINT  DD  SYSOUT=A
//SYSUDUMP  DD  SYSOUT=A
//SYSABEND  DD  SYSOUT=A
//ISMDD     DD  SYSOUT=A
//LIST      DD  SYSOUT=A
//TAPE0     DD  DUMMY
//TAPE1     DD  DSN=TUT,LABEL=(1,SL),UNIT=(TAPE,,DEFER),
//              VOL=SER=xxxxxx,DISP=(NEW,KEEP),
                DCB=(RECFM=U,BLKSIZE=4656,DEN=4)
//TAPE2     DD  DUMMY
//TAPE3     DD  DUMMY
//DISK01    DD  DSN=PARSRCDS,DISP=OLD
//SNAPDDXX  DD  DUMMY
//CARDIN    DD  *
 LOAD ADDRESSES 1601 TO 4F0B,N,381             20,000 SMALL RCDS
 LOAD ADDRESSES 5000 TO 680B,N,1055      1     20,000 LARGE RCDS
 STC     LOAD  DISKFILE             3380
 RUNID CRS01         A1L1                STV or PHASE 3
 MSG
*1
AM0SG    GSTAR 1.
AM0LIT   ENT   X'010000'.              <------ Terminal I.D.
AM0NP1   ENT   X'6C'.                  <------ ALC NOP Character
AM0NP2   ENT   X'6C'.                  <------ ALC NOP Character
23       ENT   X'7D5AD6115AD1'.        <------ Simulation of Enter key
29       ENT   ZDSYST.                 <------ Message text
         GEND
*2
AM0SG    GSTAR 1.
AM0LIT   ENT   X'010000'.              <------ Terminal I.D.
AM0NP1   ENT   X'6C'.                  <------ ALC NOP Character
AM0NP2   ENT   X'6C'.                  <------ ALC NOP Character
23       ENT   X'7D5AD6115AD1'.        <------ Simulation of Enter key
29       ENT   ZDTIMT.                 <------ Message text
         GEND
*3
AM0SG    GSTAR 1.
AM0LIT   ENT   X'010000'.
AM0NP1   ENT   X'6C'.
AM0NP2   ENT   X'6C'.
AM0TXT   ENT   ZDSYST.
         GEND
*4
AM0SG    GSTAR 1.
AM0LIT   ENT   X'010000'.
AM0NP1   ENT   X'6C'.
AM0NP2   ENT   X'6C'.
AM0TXT   ENT   ZDTIMT.
         GEND

Tape Requirements

The PTV utility requires the following tapes.

Tape
Description

 DBR 
Database restore (used for package test only)

 PDG 
Pool directory generation (if required)

 RTL/RTA 
Real-time log tape (always required)

 SDF 
Pilot tape (if required)

 TUT 
Test unit tape (always required)