Select task for SM2 task statistics
Component: | openSM2 |
Functional area: | Program control |
Domain: | PROGRAM |
Privileges: | all privileges bar |
Function
The START-TASK-MEASUREMENT command allows users to select a task for statistical measurement. The SM2 software monitor then gathers task-specific measurement values and enters this data in a user-specific file.
In addition to the task-specific measurement values, program counter statistics and SVC statistics can also be requested for program runs.
For the program counter statistics, a timer is used to interrupt the program at certain intervals, and the address contained in the program counter of the next instruction to be executed is transferred to the user-specific SM2 output file on each occasion (recording of program counter sampling).
For the SVC statistics, all SVC calls by the program during task monitoring are recorded, and SVC numbers and call addresses are also stored in the SM2 output file.
User task measurement is terminated by the STOP-TASK-MEASUREMENT command or on task termination, and the user-specific SM2 output file is closed. Withdrawal of authorization for task monitoring by the SM2 primary administrator (MODIFY-USER-ADMISSION TASK=*INHIBIT) and unloading of SM2 (STOP-SUBSYSTEM SUBSYSTEM-NAME=SM2) also terminate any current user task measurements.
The separate product SM2-PA is available for evaluation of the SM2 output file created during user task measurement (see the “openSM2” manual [39]).
Note
The user-specific SM2 output file may exceed the PUBLIC-SPACE-LIMIT defined for the user in the ADD-USER or MODIFY-USER-ATTRIBUTES command, even if PUBLIC-SPACE-EXCESS=*NO is specified.
Privileged functions
Privileged users (SW-MONITOR-ADMINISTRATION privilege) can monitor any task (see TSN operand).
Format
START-TASK-MEASUREMENT |
TSN = *OWN / <alphanum-name 1..4> ,FILE = *STD / *BY-LINK-NAME ,PCOUNTER-INTERVAL = *NONE / <integer 1..10000> ,SVC-STATISTICS = *OFF / *ON ,LOAD-INFO = *STD / *DETAILED |
Operands
TSN =
Specifies the task for monitoring.
TSN = *OWN
The task calling the command is monitored.
TSN = <alphanum-name 1..4>
The task with the specified TSN is monitored. The nonprivileged user may only have tasks running under its user ID monitored by SM2.
Restriction: The task SM2U, which processes the user-specific SM2 output files, cannot be monitored.
FILE =
Defines the user- specific SM2 output file.
FILE = *STD
The user-specific SM2 output file is created with default file attributes under the standard name $userid.SM2.TASKSTATISTIK.nnnn (see table "File attributes of the user-specific SM2 output file").
FILE = *BY-LINK-NAME
The user defines the file name and further file attributes himself (see table "File attributes of the user-specific SM2 output file").
File assignment takes place via the file link name PALINK. Before issuing the START-TASK-MEASUREMENT command the user must create a TFT entry with the file link name PALINK for the file to be used see ADD-FILE-LINK command.
PCOUNTER-INTERVAL =
Defines the sampling cycle (in CPU milliseconds of CPU time used by the monitored task) for program counter statistics.
PCOUNTER-INTERVAL = *NONE
Program counter statistics not activated.
PCOUNTER-INTERVAL = <integer 1..10000>
Sampling cycle (in CPU milliseconds of CPU time used). (Only those samples taken in status TU are recorded.)
SVC-STATISTICS =
The SVC calls of the task to be monitored are recorded and written to the user-specific SM2 output file.
SVC-STATISTICS = *OFF
SVC statistics not activated.
SVC-STATISTICS = *ON
SVC statistics activated. (Only those SVCs called in status TU are recorded.)
LOAD-INFO =
Defines the time at which the module load information is to be gathered.
LOAD-INFO = *STD
The module load information is gathered only at program start and program termination time (or at beginning and end of measurement).
LOAD-INFO = *DETAILED
The module load information is gathered at program start time (or at beginning of measurement) and on each load or unload activity involving the task.
If this operand is specified, SM2-PA > V1.0 can precisely convert the gathered addresses into module-relative addresses. However, the work required to do this is greater, particularly if load or unload operations take place frequently within the program.
Return codes
(SC2) | SC1 | Maincode | Meaning |
|---|---|---|---|
0 | CMD0001 | No error | |
32 | NPS0050 | System error in SM2 modules. Command rejected | |
64 | NPS0044 | No authorization to monitor task. Command rejected | |
64 | NPS0045 | Task already being monitored by SM2 | |
64 | NPS0046 | Task monitoring not initiated by START-TASK-MEASUREMENT. | |
64 | NPS0047 | Specified task does not exist | |
64 | NPS0051 | Specified task cannot be monitored by the user | |
64 | NPS0065 | No further tasks can be monitored | |
64 | NPS0066 | Invalid file attributes on the user-specific SM2 output file | |
64 | NPS0067 | DMS code ' (&00)' on macro call ' (&01)' for the user-specific SM2 file output |
File attributes of the user-specific SM2 output file
File attribute | FILE = *STD | FILE = *BY-LINK-NAME |
|---|---|---|
Definition of file characteristics | predefined | selectable |
File name | $userid.SM2.TASKSTATISTIK.tsn | filename |
Block length | BUFFER-LENGTH=STD(2) | BUFFER-LENGTH=STD(number) |
Memory allocation | SPACE = RELATIVE | SPACE = RELATIVE |
Access method | SAM | no choice, SAM format is mandatory |
Open mode | EXTEND | no choice, existing file always continued |
Format of data blocks | BLOCK-CONTROL-INFO determined by the corresponding CL2 option of the system | BLOCK-CONTROL-INFO = PAMKEY / |
The BLOCK-CONTROL-INFO=*NO operand is treated like BLOCK-CONTROL-INFO= *WITHIN-DATA-BLOCK because only the SAM format is permitted for the file.
Notes
Generation of module-related program counter and SVC statistics requires the load information (load address and length) for each module that is linked into the monitored program or which is dynamically loaded by the monitored program. This module information is ascertained by SM2 on program termination or on termination of monitoring by STOP-TASK-MEASUREMENT and written to the SM2 output file.
Under certain circumstances, the module information provided by SM2 may be incomplete, or may not be provided at all.
- No information is supplied if user task measurement is inhibited by the SM2 administrator (MODIFY-USER-ADMISSION TASK=*INHIBIT) during the program run being monitored.
- No information is supplied if SM2 is unloaded during the program run being monitored (STOP-SUBSYSTEM SUBSYSTEM-NAME=SM2).
- No information is supplied for modules unloaded during the program run being monitored.
- Incomplete information is supplied if the program being monitored is using overlays. Samplings and SVCs occurring in overlaid modules are attributed to the module loaded on termination of monitoring.
No information is supplied for modules/subsystems loaded as shared code.
No information is supplied for programs linked without a test support option.
No information is supplied for code sections not generated via load operations (e.g. if the coding was transferred to the dynamically requested memory by means of a MOVE instruction).