Monitoring a VM with job variables (MONJV)

Job variables (JVs) are memory areas used for exchanging information. They can be addressed on a command level and on a program level. They have a path name and are stored in the file catalog.

In VM2000, job variables are used to transfer information from VM2000 to an instance which is to monitor a VM. Virtual machines can thus be monitored using job variables.

When the VM is initialized (see "Initializing a VM"), a monitoring job variable (MONJV) is defined for this purpose.
The location and validity of the MONJV correspond to the runtime environment of the sender of the command. VM2000 manages and updates the MONJV as long as the VM exists. By using appropriate procedures, the VM2000 administration can automatically react to the information stored in the MONJV and thus facilitate VM2000 administration.

When the VM has been terminated, the MONJV is retained as a user job variable.

The monitor VM cannot be monitored with a MONJV.

VMs initialized with /ACTIVATE-VM-DEFINITION can also be monitored with job variables. Detailed information can be found in the section "Working with VM definitions".

A prerequisite for working with job variables is the software product JV. For more information on job variables, see the manual “Job Variables” [17], especially the section “Monitoring jobs/programs with job variables”.

For an example of how to use a MONJV to monitor a VM, see the end of this section.

MONJVs can also be used to monitor VM Migrations and main memory reconfigurations.

Beginning and end of monitoring

The MONJV used to monitor the VM is configured when the VM is initialized (see "Initializing a VM") by specifying the MONJV operand. The monitoring of the VM begins at this point; the MONJV is supplied with data by VM2000.

If a MONJV already exists with the specified name and with a password, this password can be specified in the operand JV-PASSWORD to check for access authorization.

The monitoring ends as soon as the VM is terminated, after migrating the VM or when VM2000 is terminated (implicit /DELETE-VM VM-ID=*ALL). Even when the monitoring has finished, the MONJV is retained as a user job variable without MONJV protection.

Protecting the MONJV

The operating system protects the first 128 bytes (system area) of the MONJV from unauthorized write access.

The MONJV itself is protected against deletion of or changes to the protection attributes. To prevent inconsistencies, the BS2000 systems support staff must not cancel this protection. If necessary (e.g. if the system has been terminated abnormally in the monitor system without a restart), the MONJV protection can be canceled with:

/MODIFY-JV-ATTRIBUTES JV-NAME=<monjv name>,
                      PROTECTION=*PARAMETERS(MONJV-PROTECTION=*NO)

When the VM has been terminated normally, the MONJV is retained as a user job variable (status $T) without MONJV protection.

Location of the MONJV

The MONJV can be created on any pubset in the monitor system. Valid catalog and user IDs of the MONJV depend on the runtime environment of the sender of the command.

Command entry from user task

Privileged users (TSOS) can create the MONJV for any user ID they wish. Nonprivileged users can create the MONJV only for their own user ID.
If catalog and user IDs are not specified, the MONJV of VM2000 will be created (shared) for the user ID of the sender of the command and without a password, if no job variable with the specified name already exists there.

Command entry from KVP console or logical console

The sender of the command without an operator logon can only create the MONJV for TSOS.
If catalog and user IDs are not specified, the MONJV of VM2000 will be created (shared) for TSOS on the home pubset of the monitor system and without a password, if no job variable with the specified name already exists there.

For senders of commands with operator logons, the location is defined, depending on the settings of the operator logon, in the same way as for Command entry from user task.

Command entry via $VMCONS

The user ID and operator role for a command entry via $VMCONS are: VMCONS-OPERID and VMCONS-OPERATOR-ROLE (see "Setting up the VM2000 monitor").
The location of the MONJV is defined, depending on the settings of VMCONS-OPERID and VMCONS-OPERATOR-ROLE, in the same way as for Command entry from user task.

Recommendation

When preparing to use a MONJV, the VM2000 administration must carry out the relevant administrative actions needed to coordinate the creation of MONJVs and access to the MONJVs.
If, for instance, the same MONJV is accessed by different IDs, it is advisable to have previously configured and made this MONJV known centrally with the appropriate protection attributes. The MONJV must then be addressed in the VM2000 commands and when accessing its contents, by specifying its catalog and user IDs.

Values for the MONJV

A MONJV for a VM comprises a system part (bytes 1-128) and a user part (bytes 129-256). Specific values are entered by VM2000 in the system part of the MONJV at specific times as long as the VM exists.

Byte	Meaning / possible values
1-3	Monitoring status (left-aligned, padded with a space): $S  : VM initialization initiated (Creation Started) $A  : VM initialization terminated with error (Creation Aborted) $I  : VM initialized (VM status INIT-ONLY) $R  : VM running (VM status RUNNING) $D  : guest system terminated on the VM (VM status DOWN) $H  : VM stopped (VM status IN HOLD (WAIT)) $T  : VM terminated (Terminated, VM status NOT INITIALIZED)
4	Reserved, has the value zero (0)
5-8	Reserved, contains spaces
9-12	Catalog ID of the home pubset of the monitor system (left-aligned)
13-16	Reserved, contains spaces
17	Type of MONJV: character V (VM2000)
18-20	Current system sequence number (<integer 1..999>)
21-36	Beginning of monitoring (opening the MONJV) in UTC time (format: yyyy-mm-ddhhmmss)
37-70	Reserved
71-78	Name of VM (<name 1..8>, not for status$S and $A)
79-81	Index of VM printable (<name 3..3>, e.g. 002)
82-86	Status of guest system: NONE  : guest system not loaded (for $I and $T) START : guest system in startup phase (for $R and $H) READY : guest system has SYSTEM READY (for $R and $H) RSTRT : restart in guest system (for $R and $H) NTERM : guest system terminated with SHUTDOWN (for $D and $H) ATERM : guest system terminated by SETS or VM administrator (for $D and $H)
87-94	Migration status of the VM: MIGR-OUT: The VM is being migrated to another Server Unit
95-128	Reserved
129-256	Reserved for users

Displaying the MONJV

You can query the contents and attributes of the MONJV using the commands and macros for job variables, e.g. /SHOW-JV and /SHOW-JV-ATTRIBUTES (see the “Job Variables” manual [17]).

The name of the MONJV is displayed in the VM2000 commands /SHOW-VM-ATTRIBUTES and /SHOW-VM-RESOURCES using the operand INFORMATION=*MONJV/*ALL as VM-MONJV.

Behavior during Migration of the VM

MONJVs used to monitor VMs are not migrated to the target SU during a VM Migration. After the VM has been terminated on the local Server Unit, the MONJV is retained as a user job variable. After successful migration of the VM to the target SU, the MONJV is set to monitoring state $T (VM terminated).

A migrated VM cannot be monitored with a MONJV.

Behavior when the system is terminated abnormally in the monitor system

MONJVs are retained in the monitor system when the system has been terminated abnormally. They have the same status at first as was set before the system was terminated abnormally. When the monitor system is restarted, the MONJVs are updated as soon as possible.

If a VM in the computer network is monitored by a system or a VM outside the monitor VM, the program monitoring it must always take the network status of the monitor VM into consideration. HIPLEX MSCF also offers MONJVs to monitor the network status, see the “HIPLEX MSCF” manual [10 ], especially the section “Monitoring the network status”.

Without restarting the monitor system

MONJVs remain in the same status (with MONJV protection) as before the system was terminated abnormally. Changes to status cannot be displayed.

In a later session this MONJV can be used again to monitor a newly intialized VM (see "Initializing a VM").

With a restart of the monitor system

The MONJVs also remain valid in the session which is initiated by the restart.

If the status of the guest system or of the VM is changed during the restart phase, the MONJVs are updated as soon as the corresponding pubset can be accessed:

• The MONJVs are updated on the home pubset on SYSTEM READY.

• MONJVs on a data pubset are updated after the pubset has been imported. If the pubset is still not available after an hour, no further attempt is made to access the MONJVs. If the status of the guest system or the VM changes after this, VM2000 makes another attempt to update the relevant MONJV. For every attempt made to access a MONJV which fails, the message VMS4343 is output at the BS2000 console of the monitor system.

Example

The following sample procedure can be used, for instance, to execute follow-up processing (e.g. data backup) after the guest systems have been shut down (e.g. using /SHUTDOWN-VM VM-ID=*VM-GUESTS).

/SET-PROC-OPT
/" **************************************************************"
/" ** PROCEDURE VMCHECK                                   *******"
/" **************************************************************"
/" ** THE PROCEDURE IS CALLED UP IN THE MONITOR SYSTEM.          "
/" ** VMS NOT RUNNING ARE TERMINATED.                            "
/" ** WAITING FOR TERMINATION OF SYSTEM FOR RUNNING VMS.         "
/" ** IMPORTANT STEPS:                                           "
/" ** - CONNECTION TO VM2000 ESTABLISHED                         "
/" ** - CONFIGURED VMS CHECKED                                   "
/" ** - VMS NOT RUNNING ARE TERMINATED                           "
/" ** - WAITING FOR TERMINATION OF SYSTEM IN GUEST SYSTEMS BY    "
/" **   EVALUATING THE MONJV                                     "
/" ** - DISCONNECTION FROM VM2000                                "
/" **************************************************************"
/" **************************************************************"
/DECLARE-VARIABLE NAME=SHVMR(TYPE=STRUCTURE),MULT-E=*LIST
/DECLARE-VARIABLE NAME=TXT(TYPE=STRING,INIT-VALUE='OK')
/DECLARE-VARIABLE NAME=I(TYPE=INT)
/ASSIGN-SYSLST LST.VMCHECK
/MODIFY-JOB-OPTIONS LOG=*PAR(LIST=Y)
/MAIN: BEGIN-BLOCK DATA-INSERT=Y
/"** CONNECTION TO VM2000 "
/BEGIN-VM-DIALOG VM-ID=1
/"** CHECK VMS AND THEIR STATE "
/EXEC-CMD (SHOW-VM-RESOURCES INF=*ALL),STRUCT-OUT=SHVMR
/FOR I=*COUNT(FROM=2, TO= SIZE('SHVMR'), INCR=1 )
/"** TERMINATE VMS THAT ARE NOT RUNNING"
/ IF (SHVMR#I.STA NE '*RUN')
/  DELETE-VM VM-ID=&(SHVMR#I.VM-INDEX)
/  IF-CMD-ERROR
/   TXT = 'NO TERMINATION OF VM &(SHVMR#I.VM-INDEX)'
/   GOTO LABEL = ERROR 
/  END-IF
/ ELSE     "**  WAIT FOR GUEST SYSTEM TERMINATION **" 
/  WAIT-EVENT *JV(((&(SHVMR#I.VM-MONJV),1,2) <> '$R'),TIME-LIM=300)
/  IF-CMD-ERROR
/   TXT = 'NO SHUTDOWN IN VM &(SHVMR#I.VM-INDEX) '
/   GOTO LABEL = ERROR 
/  END-IF
/  JVMON = JV(SHVMR#I.VM-MONJV)
/  IF NOT (SUBSTRING(JVMON,1,2) = '$D' AND SUBSTRING(JVMON,82,5) = 'NTERM')
/   TXT = 'VM &(SHVMR#I.VM-INDEX) NOT TERMINATED REGULARLY'
/ SEND-MSG TO=OPER,MSG='*** WARNING IN VMCHECK: &TXT ***'
/   TXT = 'NOT ALL VMS TERMINATED
/  ELSE
/   DELETE-VM VM-ID=&(SHVMR#I.VM-INDEX)
/  END-IF
/ END-IF
/END-FOR
/END-BLOCK MAIN
/IF-BLOCK-ERROR         "HANDLE OTHER ERRORS"
/ TXT = 'OTHER ERRORS'
/ GOTO LABEL = ERROR
/END-IF
/"** NORMAL END "
/ERROR:
/END-VM-DIALOG VM-ID=1       "SHUT DOWN CONNECTION TO VM2000"
/IF-CMD-ERROR; END-IF
/IF (TXT = 'OK')
/ SEND-MSG TO=OPER,MSG='*** VMCHECK: ALL GUEST SYSTEMS TERMINATED ***'
/ELSE 
/ SEND-MSG TO=OPER,MSG='*** ERROR IN VMCHECK: &TXT ***'
/END-IF 
/MOD-JOB-OPTIONS LOG=*PAR(LIST=NO)
/ASSIGN-SYSLST *PRIMARY
/END-PROC