bkstat (UNIX)
The bkstat utility reports on the status of KCML partitions and gives some system information about the KCML processes. The meaning of the information in a bkstat listing is shown in table 1.
Each page contains typically up to 16 partitions. At the bottom of the screen is a menu bar. To see more partitions or to refresh the screen if there are less than a screenfull select Next with the space bar or by pressing the letter `N' and press RETURN.
To leave the utility position the reverse video block at the Quit option with the space-bar or by pressing the letter 'Q'. Then press RETURN.
To see more detail on one particular partition choose the Detail option. This allows the cursor to be aligned with one particular partition and when RETURN is pressed process information is displayed similar to that produced by the Unix ps -l command.
If any partition is not in use, then the PID field for that partition will be highlighted. These entries may be cleared with the Clear option on the menu which allows the cursor to select the partition to be cleared. Examples of unused partitions are KCML processes that be been abnormally terminated, pehaps due to a 'kill -9'. Below is an example of a bkstat listing:
The parameters available with the bkstat utility are as follows:
| Switch | Purpose |
|---|---|
| -a | Display alternate page (see table 2) |
| -c part | Clear the entry for the specified usused partition. |
| -C | Clear entries for all unused partitions. |
| -D part | Display process information for the specified partition |
| -g | If specified, information for all partitions on the machine is displayed irrespective of TERMFILE use. Normally bkstat only shows those partitions whose owners share the same TERMFILE. |
| -k | If specified, bkstat returns the shared memory partition identifier. This information can also be obtained with the UNIX ipcs command. The partition can be removed with the ipcrm command, both the shared memory and the semaphore must be removed. |
| -p pid | If specified, bkstat displays all the normal information for the specified process only. |
| -P part | If specified, bkstat displays all the normal information for the specified partition only. |
| -M | List all the partitions together with the memory used for data. |
| -s | Allows access to the Signal option on the bkstat ring menu. Options in the signal menu are shown in table 3 below. The option to Terminate a process should always be used in preference to the option to Kill. Killing processes can be dangerous as not all locks may be removed, and/or shared memory space cleared. The Kill option should only be used as a last resort. |
| -S | Displays the status information about each $PSTAT semaphore. Semaphores that are shown as LOCKED are locked with the @LOCK statement. If the process executing an @LOCK dies then it is possible that the global will remain locked. Use bkstat -u to unlock the global. |
| -t term_no | If specified, display the information for the specified terminal. If the terminal is not in use then nothing is returned. |
| -T | If specified, displays the $PSTAT, terminal id number. This is a unique number taken from the UNIX inode number of the TERMFILE file (see the KCML Environment configuration section). This number is used to attach KCML processes to Global partitions. |
| -u [semid] | Unlock $PSTAT semaphore previously locked with the @LOCK statement, see the -S option. |
| -w | Wide display page. Shows all attributes of a partition. Note that this is only suitable for wide screens of 128 characters or more. |
| -r | Displays the KPrint Licence Table that is managed by the Remote Licence Daemon. |
| -x size | Set the size of the $PSTAT partition array to allow size partitions. See Configuring $PSTAT |
| -y size | Set the size of the $PSTAT terminal array to allow size terminals. See Configuring $PSTAT |
| -R size | Set the size of the KPrint Licence table to allow size KPrint servers. See Configuring $PSTAT |
| -B part_no | Sends the Broadcast signal a KCML partition that is using the current TERMFILE.
part_no = 0 : Send broadcast to all partitions part_no > 0 : Send broadcast to partition part_no part_no < 0 : Send broadcast to all partitions execpt part_no To send the broadcast signal to every KCML process in the partition table add -g flag. |
| -K part_no:sig[:action] | General purpose signalling flag. This will send the signal sig to the specified partition. The optional action field is used with the SIGUSR2 signal. It has the following values:
Snoop: causes the KCML process to genereate a screen dump file. See $ALERT SCREEN. Panic: causes the KCML process to genereate a PANIC file, program execution continues. See PANIC CONTINUE. Panic+: causes the KCML process to genereate a screen dump file, the KCML process then aborts. See PANIC. Broadcast: causes the KCML process to display the current value of $MSG on the terminal. Stacktrace: causes the KCML process to send the kcml.proc.stacktrace performamce metric to a RabbitMQ server. If part_no is zero then bkstat will attempt to signal all partitions. |
| -F | Lists all foreground KCML partitions that are attached to a terminal. When executed by user root bkstat will display all foreground partitions for all possible values of $SYSTEMID. This is a replacement for the Unix who and finger commands which would not show KCML sessions invoked by the Connection Manager |
The bkstat utility uses the KCML TERMINFO database and the value of the KTERM or TERM environment variables to discover how to control the screen. It supports dynamic screen sizing for screen depth. Output can also be redirected as in
bkstat -M >mem.txt
| Column | Heading | Description |
|---|---|---|
| 1 | PART | Partition number. |
| 2 | TERM | The terminal number. |
| 3 | USERMSG | Any $PSTAT message set by program. |
| 4 | USERID | The name of the user running KCML. |
| 5 | @NAME | DEFFN @PART name if global. |
| 6 | VER | KCML version number, 30 for versions <3.10.00, 31 for versions >3.00.00 and <3.20.00, etc. |
| 7 | ERR | The number of the last error recorded in the partition, including the minor error code. |
| 8 | DEV | Device number or event code if blocked. |
| 9 | PID | Process id number. |
| 10 | GLOB | Current global partition selected. |
| 11 | TEXT | Partition number of text being executed. |
| 12 | DATA | Partition number of RESTORE pointer. |
| 13 | S | Terminal status (A/D/W). |
| 14 | P | Programmability - `P' if the partition is programmable. |
| 15 | T | On simple systems with only one TERMFILE this column should be '0' for all partitions. On complex sites with more than one TERMFILE, bkstat -g shows all partitions, grouping them by TERMFILE, '0', '1' |
| 16 | F | Terminal type. Possible values, in bold, are:
Forms (KClient) Text (WDW) Batch program, executed with the -p switch Support None, eg vt100 terminal Web service, KCML SOAP server that is using a [SOAP] licence For memory mapped partition files the value is G |
| Column | Heading | Description |
|---|---|---|
| 1 | PART | Partition number |
| 2 | TERM | The terminal number |
| 3 | USERID | Logged on userid |
| 4 | DEV | Device number or event code if blocked see $PSTAT for a list |
| 5 | PID | The process ID |
| 6 | CHILD | Partition number of $RELEASEd child |
| 7 | CHAIN | |
| 8 | Mem | The size of the dynamic data segment in 1024 byte pages (see LIST SPACE) |
| 9 | LastAcc | Time since last access (key press, mouse click etc). |
| 10 | IPADDR | IP address or computer name of client |
| 11 | SERIAL | WDW serial number |
| Option | Purpose |
|---|---|
| Halt | Force the program to halt and enter the debugger. This is only possible if programming is enabled and the process is attached to a terminal otherwise it will be ignored. |
| Reset | Force the program to reset and enter the debugger in the console window. This is only possible if programming is enabled and the process is attached to a terminal otherwise it will be ignored. |
| Alert | Sends a $ALERT to the process. |
| Screen | Forces the process to generate a screen dump file provided the process is attached to a terminal. See $ALERT SCREEN for more information. |
| Panic | Causes the target process to generate a PANIC file. The process continues to run. |
| Panic+ | Causes the target process to generate a PANIC file and to terminate. |
| Broadcast | Send the Broadcast signal to the partition. If the terminal is using KClient or WDW then a dialog box displaying the current value of $MSG is displayed. This is useful alternative to the Unix wall command |
| Terminate | Requests the target process to terminate gracefully as if executing a $END at the point it next requires input from the client. If already waiting on a form event or on keyboard input it will terminate immediately. If executing a transaction it will note the request and terminate when it next reads the keyboard which ought to be outside the transaction. |
| Dump | This causes the process to terminate immediately producing a core dump file. It may interrupt a transaction. |
| Kill | This also causes the process to terminate immediately but without a core file. It may interrupt a transaction and should only be used if Terminate was ineffective. |
The signal menu has no effect if the NOPROG, NOHALT or NORESET environment variables are set.