|
Using the Version Control System |
|
The main purpose of the Version Control System is to track changes and keep your programs and files up-to-date. This generally consists of committing additions, modifications and deletions within your application to the repository, as well as updating your application with changes by other developers from the repository.
You can edit programs as you always have using your favorite editor. You can edit a program in the application directory by using the *IT - Integrated Toolkit, Ed+ program editor, *E character-based editor or the Command line. If your favorite editor is a text editor, edit from the source directory; however, this will require an extra step later on. Edit panels from the application directory using the NOMADS Panel Designer. Native data files that have been flagged for conversion to formatted text files can be edited using existing file maintenance for that file within the application.
You can also edit programs, panels or flagged data files by right clicking on the file in the source directory and selecting Edit from the popup menu. This invokes the default program editor for editing programs (either the *IT - Integrated Toolkit or Ed+, depending on the setting for the %NOMADS'Program_Editor property), the NOMADS Panel Designer for panels, or the File Update Utility for flagged data files.
It is important to keep the source and application directories in sync when modifying files. If you were to modify and save a program from either the application or source directory by using *IT - Integrated Toolkit, Ed+, *E or the Command line, then the PxPlus Version Control System will automatically synchronize the program in the other directory. This is because whenever a program is saved using the PxPlus SAVE directive, special administrative files are accessed (.pluscvs files in the application directory and .cvsplus in the source directory) to determine where to update the corresponding program. In addition, when you modify a screen panel using the NOMADS Panel Designer, the corresponding source file is updated automatically as well.
Whenever a flagged data file in the application directory is modified, the .pxdat text file in the source directory is automatically updated when the modified data file is closed. There is even special logic in the PxPlus Report Writer to update the source directory whenever a report definition (.pvr) or report library (.pvrlib) file is created or updated.
If you use a text editor to modify programs or text versions of data files in the source directory, or copy modified programs into the application directory, then the source and application directories will no longer be in sync. In these cases, you will have to perform an extra step to re-sync the directories. In the case of modifying source files with an external editor, you will have to manually update the application directory. This can be done using the SVN command line program with the APPUPDATE option, as in SVN APPUPDATE PATH. The path can be a directory or file name and can reference either an application or source directory.
Examples:
svn appupdate c:\development\myapp ! Updates all files in myapp and its subdirectories
svn appupdate c:\development\myapp\myprog ! Updates just myprog
In the case of copying files into the application directory or modifying resource files or data files in the application directory that are not flagged for text conversion, to update existing files, you will have to manually refresh the source directory. This can be done using the SVN Command line program with either the REFRESH or REFRESHALL options, as in SVN REFRESH PATH.
For the REFRESH option, the path argument can be the source or application path of a directory or file. If a directory is specified, only the files in that directory level are processed; processing is not recursive.
To process the directory and its subdirectories, use the REFRESHALL option, which requires a directory path as an argument. The REFRESH options only affect files currently existing in the source directory.
If a new directory, panel library or resource file is added, you will have to use the ADD option of the SVN command line program to extract it into the source directory and then add it to the Repository, as in SVN ADD PATH.
See Adding Files and Adding Directories and Panel Libraries.
Examples:
svn refresh c:\work\mysrc ! Refreshes files in mysrc
svn refreshall c:\work\mysrc\progs ! Refreshes files in progs and its subdirectories
Native data files that have been flagged for conversion to formatted text files automatically have their text files updated in the source directory when they are closed after modification. This is useful for keeping track of changes to definition files, such as data dictionary and views definition files, or configuration files.
To flag a data file for conversion, you can select the Convert to Text for Version Control System check box option for the file definition in Data Dictionary Maintenance and update the file. Alternately, you can use the SVN command line program with the TEXTON or TEXTOFF options to set/reset the flag.
Examples:
svn texton \app\data\providex.ddf
svn texton \app\data\providex.dde
Adding new files to the system is a multi-step process that includes adding the file to the application directory, adding the corresponding format in the source directory, adding the file to the Version Control System, and finally, committing the file to the repository. Depending on the type of file and how it was created, many of these steps have been combined to make the process simpler. For example, the SVN ADD command will extract a file from the application directory to the source directory, as well as set it up in the Version Control System.
To add a new program, create and save it in the application directory, or source directory if created in a text editor. If the new program is created by using the *IT - Integrated Toolkit, Ed+ program editor, *E character-based editor or the Command line, the source directory will automatically be updated. If using a text editor or copying the new program from elsewhere, you will have to sync the directories as described earlier. New programs will be added to the repository when they are included in a commit command, or you can use the SVN command line program with the ADD option.
To add a new data file, use Data Dictionary Maintenance to create the file. If the data file is flagged for file conversion, the text version will automatically be created and updated in the source directory. You can also create new data files without embedded dictionaries using the appropriate language directive, and then turn the conversion flag on using the SVN TEXTON command, if desired. This will also create and update the text version in the source directory. If the data file has been flagged for conversion, the system will optionally add the file to the Version System. If the data file is not flagged for conversion, or if you have chosen to skip the option that automatically added the file to the system, you will have to use the SVN ADD command to add the data file to the system.
New panels are created using the NOMADS Panel Designer, and are automatically created and updated in the source directory. Then, use the SVN ADD <library> to add the new panel to the Version Control System.
New resource files can be created in or copied to the application directory. Then, use the SVN ADD command to copy the resource file into the source directory and add it to the Version Control System.
Examples:
svn add c:\work\myapp\data\custinfo ! Adds an unflagged data file
svn add c:\work\myapp\resource\logo.jpg ! Adds a resource file
svn add c:\work\myapp\libs\scrnlib.en ! Adds a new screen library or panel
To undo all changes made in a file or directory since the last update, use the SVN command line program with the REVERT option.
Examples:
svn revert c:\development\myapp\myprogs ! Reverts all files in myprogs and its subdirectories
svn revert c:\development\myapp\myprogs\myprog ! Reverts just myprog
svn revert c:\development\myapp\mylibs\scrnlib.en ! Reverts all panels in the scrnlib.en library
svn revert c:\development\mysrc\mylibs\scrnlib.en\mypanel.pxpnl ! Reverts just the mypanel panel
To delete a program or resource file, it should be deleted from the source directory by right clicking on the file and using the TortoiseSVN > Delete menu item in the popup menu to remove it. Deleted programs will be removed from the application directory and repository when the directory in which it was located is next committed.
To undo a deletion, you must revert the parent directory, as the deleted file no longer exists.
After you have modified your programs and screen library files, added new files, deleted unwanted ones, etc., these changes exist only in your application and source directories until you commit them to the repository. Before you commit your files, however, you should make sure that your files are up-to-date with changes made by others, so you should update your files first to determine if there are any conflicts and resolve them. See Updating Your Files. When your files are up-to-date and there are no conflicts, you are ready to commit your changes.
Several methods are available to commit your changes:
The TortoiseSVN Commit procedure will present a change list of all modified files in the specified directory and its subdirectories. You can check the files you wish to be committed. If files are specified to be committed, they will appear in the change list if they have been modified.
When committing your files, be sure to include a brief description of the changes you have made to the files for future reference. Once committed, your modifications will be available to other developers when they update their files from the repository.
If many people are working on the same code base, you should periodically update your source and application directories to ensure that changes done by others are incorporated. An update consists of merging any changes done by others into your source directory files, keeping any changes you may have done to the same files. Conflicts can occur during an update, however, if others changed the same lines in the same file as you. TortoiseSVN has an external merge tool to resolve such conflicts. After the TortoiseSVN update is complete, the PxPlus Version Control System automatically updates the application directory with the new program versions. The repository is not affected by an update.
Several methods are available to update your files:
If a directory path is specified for an update procedure, processing will be recursive to subdirectories.
During an update, it is possible that some of the files being updated in the application may be in use by other tasks. This prevents the update from having exclusive access to the file being transferred. This can affect the transfer of PxPlus data files and resource files (i.e. non-PxPlus files such as text files, media files, documents, etc.).
Exclusive access means that the receiving file can have a different file definition, it can be purged of the old records, and all new records can be written cleanly. Without exclusive access, if the file definition has changed, then the file cannot be updated and a transfer error will be reported in the Application Update summary. If, however, the file definition has not changed, then the old records can be removed individually to clear the file prior to writing the new records. In this case, it is possible that records extracted by another task may not be available to remove or rewrite, resulting in possible lost data.
When a file is in use by another task, three options are available:
|
Option 1: |
Retry opening the file with exclusive access. |
|
Option 2: |
Open the file without exclusive access and continue. Warning! |
|
Option 3: |
Cancel converting the file. |
Option 1 allows you to close down other tasks that may be using the file and retry the transfer.
Option 2 allows the process to continue with non-exclusive access to the file. Data loss is possible, but only if records are extracted by other tasks. If data is lost, then a warning will appear in the Application Update summary.
Option 3 cancels the file transfer and reports an error in the Application Update summary. If there is an issue during the file transfer, the file in question can be updated individually at a later time when exclusive access is available.
When a new directory is added to the application, a corresponding directory must be created in the source. Then, the contents of the new directory must be extracted into the new source directory, then added and committed to the repository. This can be done in a single step using the ADD option of the SVN command line program, as in SVN ADD PATH. The ADD option also sets up version control administration files for new directories. New panel libraries and resource files may also be added this way.
Examples:
svn add c:\work\myapp\images ! Adds the images directory and subdirectories
svn add c:\work\myapp\libs\scrnlib.en ! Adds a new screen library or panel
To retrieve a new directory or screen library, do a source update on a directory containing the new directory/files. The source and application files will be added automatically.