BS2000 commands for activating user task monitoring

Any user can have SM2 monitor tasks under his/her own ID, provided the SM2 primary administrator has given permission for the user-specific monitoring program (by issuing the SM2 statement MODIFY-USER-ADMISSION TASK=*ALLOW. The total number of tasks which can be monitored simultaneously is limited to 16).
Only users who have been assigned the system privilege SW-MONITOR-ADMINISTRATION can start or terminate monitoring of any tasks.

Function

The BS2000 command START-TASK-MEASUREMENT is used to specify the tasks to be included in the monitoring process. The SM2 monitoring program then records task-specific monitored data and enters this data in a user-specific file.

In addition to task-specific monitoring data, program counter statistics and SVC statistics on program runs can also be requested.

In the case of program counter statistics for counting commands, the program is interrupted at defined intervals (using a timer) and the address of the next command to be executed and contained in the program counter is transferred to the user-specific SM2 output file (registering the number of times the counter sampled the program).

In the case of SVC statistics, all SVC program macros called during task monitoring are recorded, and SVC numbers and macro addresses are also stored in the SM2 output file.

If the BS2000 command STOP-TASK-MEASUREMENT is issued or the task is terminated, user task monitoring ends and the user-specific SM2 output file is closed. In addition, withdrawal of the primary SM2 administrator’s permission for the user-specific monitoring program TASK (MODIFY-USER-ADMISSION TASK=*INHIBIT) as well as deactivation of SM2 (STOP-SUBSYSTEM SUBSYSTEM-NAME=SM2) will terminate any currently executing task measurement operations.

The product SM2-PA is provided to analyze the SM2 output file generated for user task monitoring (for further information, please refer to the “SM2-PA” manual [15 (Related publications)]).

The user-specific SM2 output file can exceed the limit specified for the user by PUBLIC-SPACE-LIMIT in the ADD-USER- or MODIFY-USER-ATTRIBUTES command, even if PUBLIC-SPACE-EXCESS=*NO is specified.

Formats

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

STOP-TASK-MEASUREMENT

TSN = *OWN / <alphanum-name 1..4>

Operands

TSN =
Specifies the task to be monitored or for which monitoring is to be terminated.

TSN = *OWN
The task invoking the command will be monitored or monitoring of that task will be terminated.

TSN = <alphanum-name 1..4>
The task with the TSN specified is monitored or monitoring of that task is terminated. Only users who have been assigned the system privilege SW-MONITOR-ADMINISTRATION can start or terminate monitoring of any tasks. All other users can only monitor their own tasks.
Restriction: The task SM2U, which processes the user-specific SM2 output files, cannot be monitored.

FILE =
Specifies the user-specific SM2 output file.

FILE = *STD
The user-specific SM2 output file contains the file attributes which are defined in the following table.

FILE = *BY-LINK-NAME
The user defines the file name and further file attributes using the corresponding BS2000 commands. The file is assigned via the link name. The link name for the user-specific SM2 output file is PALINK.

PCOUNTER-INTERVAL =
Defines the sampling cycle for command counter statistics (in CPU milliseconds).

PCOUNTER-INTERVAL = *NONE
Command counter statistics are not activated.

PCOUNTER-INTERVAL = <integer 1..10000>
Sampling cycle in CPU milliseconds. The only samples recorded are those with the status TU.

SVC-STATISTICS =
The SVC macros of the task to be measured are recorded and written to the user-specific SM2 output file.

SVC-STATISTICS = *OFF
SVC statistics are not activated.

SVC-STATISTICS = *ON
SVC statistics are activated. The only SVCs recorded are those with the status TU.

LOAD-INFO =
Specifies the point at which the module loading information is to be recorded.

LOAD-INFO = *STD
The module loading information is only recorded when the program is started or terminated (or when monitoring is started or terminated).

LOAD-INFO = *DETAILED
The module loading information is recorded when the program is started (or when monitoring is started) and every time the task performs a load or unload operation.

Command return codes

(SC2)	SC1	Maincode	Meaning
	0	CMD0001	No errors
	32	NPS0050	System error in SM2 modules, command rejected
	64	NPS0044	No authorization for monitoring task, command rejected
	64	NPS0045	Task already monitored by SM2
	64	NPS0046	Task monitoring not started by /START-TASK-MEASUREMENT, command rejected
	64	NPS0047	Specified task does not exist
	64	NPS0051	User cannot monitor specified task
	64	NPS0065	Cannot monitor any more tasks
	64	NPS0066	Invalid file attributes for user-specific SM2 output file
	64	NPS0067	DMS code '(&00)' in the case of a macro ' (&01)' for user-specific SM2 output file

You will find a general description of the command return codes in the “Commands” manual [3 (Related publications)].

Attributes of the user-specific SM2 output file

Meaning	Attribute	Attribute
Operand for file creation	FILE = *STD	FILE = *BY-LINK-NAME
Definition of file attributes	Predefined	Optional
File name	$userid.SM2.TASKSTATISTIK.nnnn 1	filename
Block length	BUFFER-LENGTH = *STD(SIZE=16)	BUFFER-LENGTH = *STD(SIZE=number) 2
Storage space allocation	SPACE = *RELATIVE (PRIMARY-ALLOCATION=48, SECONDARY-ALLOCATION=48)	SPACE = *RELATIVE (PRIMARY-ALLOCATION=number1, SECONDARY-ALLOCATION=number2) 2, 3
Access method	SAM	No selection option, SAM format is mandatory.
Open mode	EXTEND	No selection option, the existing file is always extended
Format of the data blocks	BLOCK-CONTROL-INFO is defined by the system parameter BLKCTRL	BLOCK-CONTROL-INFO = *PAMKEY/ *WITHIN-DATA-BLOCK/ *NO 4

¹ nnnn = TSN of the task to be monitored

² In the case of an SM2 output file assigned using link names, the BUFFER-LENGTH and SPACE attributes are taken from the standard file, unless specified otherwise by the user.

³ PRIMARY-ALLOCATION and SECONDARY-ALLOCATION each 48 unless defined otherwise by the user.

⁴ The BLOCK-CONTROL-INFO=*NO operand is treated like BLOCK-CONTROL-INFO=*WITHIN-DATA-BLOCK, because only SAM format is permitted for the file.

To generate module-related program counter and SVC statistics, the load information (the load address and length) of each module is required for each module which has been linked into the monitored program or is to be loaded by the monitored program. When the program or measurement is terminated by means of the /STOP-TASK-MEASUREMENT command, SM2 determines this module information and writes it to the SM2 output file.

Under certain circumstances SM2 can only supply incomplete information or none at all:

• If the program to be monitored uses overlay techniques, the module loading information should be recorded using LOAD-INFO=DETAILED. If this is not done, the samples and SVCs for all overlaid modules are assigned to the module loaded at the time monitoring is terminated.

• No information will be supplied for programs which are linked or loaded without LSD (List for Symbolic Debugging).

• No information will be supplied for code sections which were not generated with the aid of load events (e.g. if the code was put in memory dynamically requested by means of MOVE commands).