Introduction
This document aims to give an insight of each function implemented in the panels and scripts that belongs to the UNICOS backup functionality. For explanations related to unBackup user interface and widgets, refer to the unBackup User Documentation. The UNICOS backup functionality is divided into the unBackup.ctl library, unBackupCheck script, unBackup.ctl script, and unBackup.pnl panel. The unBackupLauncher.pnl will not be described here, as this panel is not used anywhere, but might be interesting to add some shortcut to launch it in the future to be able to quickly execute backups.
unBackup.ctl Library
The unBackup.ctl library contains some generic functions and others that are used by the backup check script. These are:
- unBackup_checkCtrl: Checks the state of the unBackup.ctl CTRL Manager returning False if the manager is not running, and True otherwise.
- unBackup_checkDistantBackup: Triggers a call to a function using the evalScript. By default, the function is unBackup_checkNFS, specified in the unBackup.pnl panel, and stored in the datapoint description of the unBackupCheck for the scheduler. The unBackup Check path must also be defined within the panel to execute the function.
- unBackup_checkLocalBackup: Checks the status of the local unBackup process. It checks the result of the latest local backup process, if it was OK or not, and compares that the period between the current and previous backup time is not bigger than the periodic interval selected.
- unBackup_checkNFS: Is a function introduced as input parameter in the unBackup.pnl panel inside the Function to check backup textbox. It examines that the remote backup project can be found inside the NFS remote path given and that the last modification time is within the time range of the latest execution of the backup. A few conditions must be met. 1.) The command “ls -l” must run without issues. 2.) The output of the command must not be empty and convertible into a string. 3.) The Check backup project path, which is the NFS or remote path, must include or contain a folder with the same name as the original project. 4.) The time when the online database backup has finished executing (stored in the _DataManager.Backup.Status datapoint element) minus a maximum period of time of 600 seconds given to run the unBackup.ctl script, must be smaller than the time when the project backup folder was modified.
- unBackup_getFinalpath: Obtains the Check Backup path introduced in the unBackup.pnl panel and stored in the description of the unBackupCheck.actions.script.path datapoint element. If the description is empty, the path is set by default to /nfs/cs-ccr-backup2/backup/PVSS_BACKUP/ + sHost, being sHost the string stored in the _unApplication.hostname datapoint element.
- unBackup_getManagerState: Returns the state of the unBackup.ctl CTRL Manager.
- unBackup_getProjName: Returns the project backup name.
- unBackup_getTime: Formats a date and time string to a long type for operations.
- unBackup_startStopKillCtrl: Triggers the start, kill, stop, set to always or manual manager console commands for the unBackup.ctl CTRL Manager.
unBackupCheck script
The unBackupCheck script is triggered by the scheduler whenever the unBackupCheck.command datapoint is set to 3. The script simply contains a main method that executes three functions from the unBackup.ctl library: the unBackup_checkCtrl, unBackup_checkLocalBackup, unBackup_checkDistantBackup. If the result of these three functions is True, then a message indicating that unBackup check message is Ok is sent to the expert, written in the WinCC OA log and stored in the description of the _unSystemAlarm_backup_check datapoint. Also, the _unSystemAlarm_backup_check.alarm datapoint for the alarm in the _UnSystemAlarm datapoint type will be set to 0 – OK. If one of these three functions returns False, a message indicating that the check is not Ok for that particular function will be written and the alarm will be set to 10 – Bad status.
unBackup.ctl script
The unBackup.ctl script is called from the WinCC OA Console, as it is defined as a CTRL Manager. The first time that the unBackup.ctl CTRL Manager runs, the main function is executed.
- main: When the main is triggered and if the backup folder is configured correctly, the _unApplication.backupConfigurationStatus is set to 1 and _unApplication.backupConfiguration.command datapoints is set to 0, i.e. they are initialized. Then, the functions _unBackup_callbackStart and _unBackupFilesCB are connected, using dpConnect, whenever there is a change in the unApplication.backupConfiguration.command and _DataManager.Backup.Status datapoints respectively.
- checkBackupFolder: checks if the path stored in the _DataManager.Backup.InputFile.Device is configured correctly or not.
- _unBackup_updateStatus: Sets the string introduced as input parameter in the _unApplication.unBackupStatus datapoint element and writes a debug message in the WinCC OA log.
- _unBackup_callbackStart: Checks if the unApplication.backupConfiguration.command is set to 1, meaning that a backup has been triggered, and starts a thread with the _unBackup_startOnlineBackup function if there are no other backups currently running.
- unBackup_startOnlineBackup: Triggers online backups after creating a necessary file by setting the _DataManager.Backup.Command datapoint element to 1. Then, it checks that the process has finished without any issues, updates the status and log accordingly, removes the previously created temporary files, checks the backup status from the _DataManager.Backup.Status datapoint, and updates once again the status and log. Lastly, it calls the _unBackupFiles to backup other additional files that are inside the project.
- _unBackupFilesCB: Is a callback function that is triggered when there is a change in _DataManager.Backup.Status datapoint element. It executes the _unBackupFiles function when the value stored in the backup status has changed to 0, meaning that the latest online database backup has finished, and not online backup is currently running.
- _unBackupFiles: Backs up the project files and folders, perform the appropriate operations to copy the original content to the destination folder, and update the backup status process and log. Important!! This is the core function of the unBackup.ctl script to perform the local backup copy of the files and folders of the project.
- _unBackup_writeFile: Creates the WCCOAtoolMedia file and execute it.
- _unBackup_addMissingFolder: Creates missing folders by calling _unBackup_createFolder.
- _unBackup_createFolder: Creates a specific folder by calling the mkdir function with ‘777’ mode as parameter.
unBackup.pnl panel
From the unBackup.pnl panel, there are a few functions defined that might be worth mentioning that are called when the panel initializes. These are:
- closePanel: Closes the panel.
- neeApply: Periodically checks within the while loop if the acknowledge flags have changed, meaning that some modifications have been applied, to enable or disabled the backup and check Start buttons.
- manageExceptionInfo: Sends a message to all users regarding the exception information and displays the message.
- init: Sets the backup and project name inside the General info frame by obtaining the string from _unApplication.applicationName datapoint element and calling the unBackup_getProjectName function respectively. It also calls the init_backup and init_integrity functions.
- Init_backup: Obtains the local path from the _DataManager.Backup.InputFile.Device datapoint element, and the interval from the _OnlineBackup.interval datapoint element in the _TimedFunc datapoint type to enable or disable the periodic backup checkbox depending on the value of the interval. It also initializes the next automatic execution date, time, and interval in the panel by calling _vaSetDPBackup. A thread calling the function check_unBackupCtrl is called within this function.
- check_unBackupCtrl: Periodically checks within the while loop if the unBackup.ctl CTRL Manager is running or not by calling the unBackup_checkCtrl function defined in the unBackup.ctl library. If the manager is running, the circular LED widget is set to green color and the text indicates that the manager is running. If not, the LED is set to red color and the text shows that the manager is not running.
- Init_integrity: Obtains the interval, synchronization month, day, time, and valid from/until time from the unBackupCheck datapoint and formats the values to be able to properly display them in the panel. It also calls the check_function to obtain the NFS function from the unBackupCheck description. The init_integrity function also calls the check_integritysettings.
- check_integritysettings: Simply calls the check_systemAlarm, and if it does not raise and exception, the check_scheduler.
- check_systemAlarm: Creates the _unSystemAlarm_backup_check system alarm, if it does not exist, and registers the RegisterCB callback function, if it was not already connected.
- RegisterCB: Determines whether remote system are connected or not, and depending on it, uses dpConnect and dpDisconnect to the infoCB function for the datapoint elements _unSystemAlarm_backup_check.alarm, _unSystemAlarm_backup_check.enabled, _unSystemAlarm_backup_check.alarm:_online.._stime, _DataManager.Backup.Status:_alert_hdl.._act_state_text, _DataManager.Backup.Status:_online.._stime, _DataManager.Backup.Status:_alert_hdl.._act_state_color, _unApplication.unBackupStatus, _unApplication.unBackupStatus:_online.._stime. The function infoCB will be called whenever there is a change in one of these datapoints when the RegisterCB function is registered (which should have been triggered when opening the unBackup.pnl panel).
- infoCB: Updates the check user feedback color and text, and the backup log of the unBackup.pnl whenever there is a change in the online database process, unBackup process, or unBackup check.
- check_scheduler: Creates the unBackupCheck datapoint in _Sc datapoint type with default values, if the datapoint does not exists, and adds the scheduler.
- check_function: Obtains the NFS function from the unBackupCheck description.
- stop_scheduler: Stops the scheduler by setting the unBackupCheck.mode datapoint element to false.
- start_scheduler: Starts the scheduler by setting the unBackupCheck.mode datapoint element to true.
- trigger_scheduler: Executes the backup check by setting the unBackupCheck.command to 3.
- get_scheduler_status: Gets the status of the scheduler from the unBackupCheck.mode datapoint element.
- apply_integritysettings: Sets the new interval, synchronized month, day, time, and valid from/until time to the unBackupCheck.time.timedFunc datapoint elements. It enables or disables the _unSystemAlarm_backup_check alarm if the periodic check checkbox is active or not. It sets the NFS path and function into the unBackupCheck datapoint. It starts or stops the scheduler, depending on the periodic check checkbox state, and modify the _unSystemAlarm_backup_check accordingly. The minimum interval period valid is forced to 60 seconds.
- apply_backupsettings: Sets the local path to the _DataManager.Backup.InputFile.Device datapoint element, and update the values of the date, time and interval of the backup by calling the _vaSetDPBackup function.
- userCB: Determines whether the user has access rights to the panel and enable or disable the widgets of the panel accordingly.
- do_backup: Does some string manipulation to be able to read the backup file name and opens it. If there is no issue during the process, the online database backup is triggered by setting the _DataManager.Backup.Command datapoint element to 1.
- rigthClick: Gets the unBackup.ctrl CTRL Manager state by calling unBackup_getManagerState declared in the unBackup.ctl library and displays the available console manager options. Depending on the option clicked, the manager will be started, stopped, killed, set to always or manual by calling the function unBackup_startStopKillCtrl with the corresponding parameters.