The readme contains information, not included in the manuals or online help, on installing and using the current release of Version Manager. Additional information is available in the Knowledgebase.
The Version Manager readme consists of the following files:
Installation Information (installation_info.html)
Information on system requirements and important tips on correctly installing Version Manager. Read this before installing Version Manager.
Usage Cautions (this file)
Performance tips and workarounds to help you proactively avoid undesirable outcomes. Read this before using Version Manager or attempting to recover from a critical error.
Known Issues (known_issues.html)
Information on cosmetic defects, non-critical errors, and issues for which there are no preventative measures. Look here when you experience an error or other unexpected behavior not listed in the Usage Cautions file.
Release Notes (release_notesvm.html)
A list of the defects fixed, enhancements made, and behaviors changed in each release of Version Manager. Look here to see what has changed since you last upgraded.
This readme file is organized into distinct parts. Please read the parts that correspond to the Version Manager components you are using.
Part 1: Version Manager CLI, Desktop Client, File Server, and PCLI
Part 2: Version Manager IDE Client
Part 3: Version Manager Web Client
Part 4: Version Manager WebDAV Server
Part 5: Copyright/Disclaimers/Support
|
Part 1: Version Manager CLI, Desktop Client, File Server, and PCLI |
Starting with the VM 8.6.3.3 patch, significant security enhancements affecting PVCS VM File Server Path Map Security have been implemented.
Path Map Security forces clients to authenticate with the PVCS VM File Server, beyond Project Database security, and is used to lock down low-level file access. (For more information, see page 45 in the attachment on KB doc S126695: Using the File Server to Enhance Performance and Security with Version Manager 8.x.)
If the File Server is configured to use Path Map Security, those Path Maps can no longer be accessed by pre-VM 8.6.3.3 clients unless Enhanced Path Map Security has been disabled.
For more information, see KB doc KM000021414: PVCS VM 8.6.3.3+ Enhanced Path Map Security.
If you use symbolic links to specify paths in Version Manager commands, the command will take longer to complete. To speed execution, specify full paths rather than symbolic links, or add the fully qualified paths of Version Manager commands to your environment.
When using the PVCS Version Manager File Server, real-time antivirus software on client PCs may degrade performance. This is because the antivirus software scans the Version Manager file cache every time the cache is updated. To avoid this performance penalty, exclude the cache directory from real-time virus scans.
By default, the file cache is in a directory named pvcsfs under your system's temporary directory (as specified by the TMP or TEMP environment variable). You can set a different location for the cache by defining a path in either the FS_TMP or FS_TEMP environment variable.
For more information on antivirus-related performance improvements, see KB doc S123872: How to Improve Version Manager Performance When Using Real-Time Virus Scanners.
Version Manager automatically cleans up old files in the File Server client cache directory whenever a Version Manager client session first contacts the File Server.
You can exert control over this feature by adding entries to your islv.ini file.
NOTE: Time values are in seconds by default, but you can specify minutes or hours using the <n>m or <n>h syntax.
New settings of interest are as follows (shown with the default values that will be used if the entry is absent):
[PVCSGUI_6.5]
pvcs.fileserver.cache.cleanup.frequency=12h
Wait at least 12 hours following a cleanup operation before attempting to clean up the cache directory again.
pvcs.fileserver.cache.cleanup.age=24h
Clean up all files that are at least 24 hours old.
pvcs.fileserver.cache.cleanup.mode=m
Determine the age of the file based on its modification time ('m'). Can also be set to 'a' (file access time) or 'c' (file creation time). The default is highly recommended as some file systems could exhibit bad behavior with the other options.
NOTE: The location of the File Server client cache directory is determined by the environment variable FS_TMP or, if FS_TMP is not defined, FS_TEMP. If neither is defined, the directory defaults to %TMP%\pvcsfs or, if TMP is not defined, %TEMP%\pvcsfs.
If you have a Windows system that uses the TZ environment variable, Version Manager will default to built-in, hard coded, USA-centric start and end dates for Daylight Savings Time.
To avoid this issue, you can use the PVCSTZ environment variable to override both the TZ variable and the time zone information that is provided by the operating system, should that be desired.
NOTE As of 8.1.4.0 (spring 2007), DST dates have been updated to reflect the current law. Also, an update with the new dates is available for Version Manager 8.1.3.2. It is attached to the KnowledgeBase article mentioned below.
See the KnowledgeBase article, Is Version Manager affected by the changes to the U.S. Daylight Saving Time (DST) for 2007?, ID 5004791, for more information.
If the content of a keyword contains a "$" character, you must use the new syntax:
$Keyword::$123456::$
Where:
Keyword is the keyword.
123456 is the length delimiter. The length is determined by the number of characters. Any characters can be used as the length delimiter.
::$ marks the beginning and the end of the length delimiter character string.
If the content of a fixed length keyword does not contain a "$" character, you may use either the new syntax or the original syntax, which follows:
$Keyword::123456$
From the command line, a dash (-) in a version label can be interpreted as a math operation upon the revision number. This can result in the incorrect revision being acted upon.
This can happen only in the circumstances described below:
A series of labels are the same save for a numeral that follows a dash. For example: Beta; Beta-1; Beta-2; Beta-3. NOTE There must be a label of the same name with no dash and no numeral (Beta, in this case).
A command is issued against a label in the series, but that label does not yet exist in the archive or it has been deleted. For example, Beta-4.
The revision acted upon in that case will be based upon the revision number of the revision with the non-numerical, non-dash label (Beta, in the example above), minus the numerical portion of the requested, but nonexistent, label.
Here is a specific example:
Revision 1.6 has the Version Label: Beta
The nonexistent label used in the command is: Beta-4
The unintended revision math performed is: 1.6 - 4 = 1.2
The revision acted upon by the command is thus: 1.2
Recommendation: If you must use such a label numbering scheme, be sure never to specify a nonexistent label in a command. Better yet, avoid the possibility of encountering this behavior by ensuring that there is not a label like "Beta" that otherwise matches the sequence of labels.
NOTE By default, Version Manager checks for illegal characters (such as dash (-)) during label creation and rejects the label if it contains illegal characters. If you must create labels that include illegal characters, you can disable the filter that checks for illegal characters in labels. See the DisableBadLabelFilter directive in the PVCS Version Manager Command-Line Guide.
If a file has over 32,000 lines, the scroll bar in the Diff/Merge tool will not work correctly. Use the Next, Previous, and Go to line features to navigate large files. Using the scroll bar alone, you may be unable to reach the desired location.
Under some circumstances, a copy project database operation may fail with a privileges error. This may occur when all of the following are true:
Sub projects are configured with access control databases.
Copy existing Configuration Files is selected.
Create a new Access Control Database is selected.
The name used to log into the operating system (the so called HOSTID) does not exist in the Access Control Database(s) of the subproject, and the copy is performed by a different username.
To work around this issue do one of the following:
Ensure that the HOST login ID exists in all access control databases of the project database. Perform the copy operation as that user.
Select the Copy Access Control Database to new location option.
Configuration Builder does not support the Version Manager File Server.
User names that contain double-byte characters and are longer than 20 characters get truncated when you close the Project Security dialog box. In some cases, they also can prevent repeated use of the dialog box.
If you remove all privilege sets from a user (via Admin | Security in the Version Manager desktop client), the user actually receives the Unlimited privilege set.
If you do not want a user to have Unlimited privileges, make sure that the user has at least one privilege set.
If the SBM server is accessed using HTTPS, SourceBridge associations from VM I-Net Web Client may fail. To solve this, add SSL certificate(s) to the JRE keystore. See KB doc: S134480: Using SourceBridge from the VM I-Net Web Client when the connection to the SBM server uses HTTPS (Secure Sockets Layer - SSL).
The SourceBridge component must be installed on Desktop Client machines to enforce association on checkin; else the checkin will occur with no association and no prompt or warning that an association is required.
If your LDAP server is configured to use Secure Sockets Layer (SSL) but there is not a certificate database in the VM_Install_Dir/vm/common/bin/OS directory or the database is missing the required SSL certificates, you will receive errors, such as:
To solve this issue, see KB doc S134480: PVCS VM: How to Configure Version Manager to use LDAP over SSL (LDAPS).
By default, the Version Manager client will deny access to conflicting path maps and display a message. In the Open Project Database dialog, conflicting path maps will be shown in red. A path map conflict occurs when a user tries to access two, or more, path maps that fully or partially overlap but reside on different servers.
See the PVCS Version Manager Administrator's Guide for information on resolving or working around such conflicts. If improperly handled, overlapping path maps can result in the wrong files being acted upon.
The Enable access control database security option must be enabled if the file server uses Path Map Security.
File server path map security is set up through the Version Manager File Server Administration utility. From the Path Map page, open the Add Path Map or Edit Path Map dialog box. If you enable either the Access control database field or the LDAP authentication checkbox, you must also check the Enable access control database security box (see below).
The Access control database security checkbox is on the General tab of the Configure Project Database dialog (from the desktop client: Admin | Configure Project). Select Security | Access Control Database from the Options tree.
If you use the INCLUDE directive in a configuration file and there are blank spaces in the path of the configuration file being included, you must use quotation marks around the path. For example, if the sample project database is installed to the default location, define the INCLUDE directive to its configuration file as:
INCLUDE "c:\program files\serena\vm\common\sampledb\archives\basecfg.cfg"
Large projects can exceed the memory allocated for Java in a variety of situations and with a variety of Version Manager interfaces.
To solve this, see KB doc: S138022: Version Manager - How to fix Out Of Memory and java.lang.OutOfMemoryError messages
The DTK call PvcsSetProjectSemaphore() is not supported by file servers. If you previously used this call to lock down the archives in preparation for builds or backups, you can achieve the same effect with archives on a file server by deselecting the Enable write access option in the Version Manager Administration Utility.
Restart the Version Manager Desktop Client after making changes to the Make Secure dialog box. If you reopen the dialog box during the same Version Manager session, it will not reflect the previous changes, and they could be lost when you close the dialog box.
The Switch User feature is not available in the VM I-Net Web Client for project databases using the SSO/CAC login source. To switch user users, click Logout, and log back in as another user.
To access the vconfig.exe and to modify the vmwfvc.dll file, you must log into Windows as an administrative user or use the Run as administrator option.
See the Visual Studio: Windows Requires Administrative User topic for more information.
If you encounter a conflict with a third-party DLL, try adding the name of the DLL to the ISLV.INI file. If there is not already a [THIRDPARTY] section in the ISLV.INI file, create one and list the conflicting DLL's under it as follows:
[THIRDPARTY]
PVCS.VM.THIRDPARTYDLLS=libeay32.dll:ssleay32.dll
Any DLL names should:
Be separated by the delimiter colon ( : )
Contain only the filename, not the full file path.
Version Manager cannot be licensed until the workstation is registered to the network. Register to the network before attempting to use Version Manager.
Allowing PIN caching by ActiveIdentity Client on Linux systems can, in certain circumstances, result in access regardless of the PIN entered. To avoid this possibility, specify a short cache retention period or disable PIN caching in ActiveIdentity Client. For obvious reasons, we are not fully describing the very specific scenario which can bring about this undesired result.
Some PCLI operations, such as ListVersionedFiles, can open many files at a time. On some UNIX systems, the default open file descriptor limit may be set too low. We recommend that you set your file descriptor limit to 128 or higher. For very large databases, we recommend setting the limit as high as allowed by the operating system. For C shell users, use the "limit" command to set the limit. For Bourne and Korn shell users, use the "ulimit" command. The default file descriptor limit varies on each operating system and by system configuration. The default limit may or may not already be set higher than 128.
A lack of file descriptors can manifest itself in various ways. Typical problems include a failure to open or locate files in response to file-intensive commands such as AddFiles, ListVersionedFiles, and ImportArchives.
When you export a project database on Windows, you can import it only on Windows; you cannot import it on UNIX without manually converting all the pathnames in the exported file and in the configuration file(s) it references. The same is true when you import a file on Windows that was exported on UNIX.
Workspace or user names that contain slashes (/ \), square brackets ([ ]), or colons (:) can cause PCLI commands and the import/export of project databases to fail. Change any such preexisting names before importing/exporting or using other PCLI commands.
|
Part 2: Version Manager IDE Client |
Version Manager allows you to configure a project database or project to always remove locks on unchanged files. If you are working with Version Manager projects within PowerBuilder, be sure to set this option. If you do not, objects in your PowerBuilder application may become out of sync with their associated versioned files when you undo a checkout or when you check in an unchanged revision. Objects may appear to be unlocked in PowerBuilder when in fact their associated Version Manager archives are still locked.
See the PVCS Version Manager Administrator's Guide for more information.
It is not enough to configure SourceBridge to require associations, you must also set the SCC provider to the issue management system you are using. Use PVCS Version Manager SCC Admin to set the SCC provider to PVCS Version Manager SourceBridge.
Server-side processing is enabled by default, so by default all event triggers will be executed on the server. If this is incompatible with your processes, you can revert to the previous behavior of client-side processing. See the PVCS Version Manager IDE Client Implementation Guide for more information (the section on setting default options for your particular IDE).
If you are using the Server-Side Processing feature of the Rich IDEs, then all File Servers containing repositories used by these integrations must be defined on the server(s) through which the RIDE users connect--including the File Server itself (as "localhost" or using its server name). To do so, see the File Server chapter of the PVCS Version Manager Administrator's Guide.
Some third-party tools create folders that fail to function properly for the third-party tool if any outside content is added to them. Since the RIDE integration adds a _serena folder when items are placed under source control, you must exclude sensitive third-party folders from source control. The ibmconfig folder is one folder known to have this issue. See the PVCS IDE Implementation Guide for details on how to exclude files or folders from source control.
The rich integration uses the default version (label) to determine which files are visible in a given Version Manager workspace. To avoid confusion, it is important that you understand how this works.
If you use the desktop client to apply a default version or change the existing one for a project database or for a workspace, only files that have the version label will appear in Visual Studio. If the project and solution files do not have these labels, you will see no files.
To avoid the potential for confusion:
Create a Version Manager workspace for any user or group of users who may need their own default version (label).
Define default versions on a workspace-by-workspace basis (File | Properties | Workspace Settings tab), rather than for the entire project database.
Remember that when you open a project from source control that you must specify the Version Manager workspace to use. If you wish to see the files and revisions defined by a different default version, then you must do an open from source control and specify the workspace that is associated with the desired label.
See the Version Manager IDE Client Implementation Guide for more information.
To improve server stability using very large data sets, the VM Web Application Server will reject pre-8.5.1 RIDE clients trying to use Server-side processing. Such clients will display a message similar to the following:
[INFO] Server-side processing can not be used with pre 8.4.1 server, switching to Client-side processing.
Please uncheck the 'Enable Server-side processing' feature available in Windows>Preference>Team>Serena>Client/Server to avoid this message.
These clients can still access the Project Database using the old-style Client-side processing, as indicated.
You can override this behavior and allow pre-8.5.1 clients access via Server-side processing by adding the following directive to server's ISLV.ini
[APP_SERVER]
pvcs.appserver.rejectClientsWithoutHugeSetsCapability=false
This should only be used if the RIDE projects are small in size and upgrading the clients to 8.5.1 or newer is not immediately possible.
|
Part 3: Version Manager Web Client |
When using the PVCS Version Manager File Server, real-time antivirus software on machine running the PVCS Version Manager Web Application Server for the Web Client may degrade performance. This is because the antivirus software scans the Version Manager file cache every time the cache is updated. To avoid this performance penalty, exclude the cache directory from real-time virus scans.
By default, the file cache is in a directory named pvcsfs under your system's temporary directory (as specified by the TMP or TEMP environment variable). You can set a different location for the cache by defining a path in either the FS_TMP or FS_TEMP environment variable.
For more information on antivirus-related performance improvements, see KB doc S123872: How to Improve Version Manager Performance When Using Real-Time Virus Scanners.
The Version Manager web server generates log files and temporary files on the server machine. These files do not cause problems, but do use up hard drive space until deleted. We recommend that you purge these files periodically.
You can periodically delete the log files generated in the following directories:
UNIX: VM_Install_Dir/vm/common/tomcat/logs
Windows: VM_Install_Dir\vm\common\tomcat\logs
Temporary files are generated on the server if the connection between the client and server is lost in the middle of a file transfer. Delete these files from the directory VM_Install_Dir\vm\inet\temp on Windows, and in the system temp directory on UNIX. Additionally, temporary files are generated from history and difference reports when users close the browser without logging out of the project. Delete these files from the VM_Install_Dir\vm\inet\temp\html directory.
Do not use any of the following characters in the name of a project:
* : | / \ ? < > " tab ~ % & ' ,
Also: Do not use ".." as a two-character name, and do not use "." or "@" as a one-character name.
Do not use any of the following characters in the name of a file:
* : | / \ ? < > " tab
Do not use any of the following characters in the name of a label:
: + - * \
Do not use any of the following characters in the name of a promotion group:
< = " ,
Do not use any of the following characters in the name of an archive:
; ,
The functionality of event triggers differs significantly in the Version Manager web client compared to the Version Manager desktop client. The difference is caused by how archives are modified. When you use the Version Manager web client to perform a task, the archives are modified by the Version Manager web server--not by the Version Manager web client. Therefore, the data and operations available to event triggers through the Version Manager web client differ from the data and operations available to event triggers through the Version Manager desktop client.
When working with event triggers, note the following:
EventWorkfile and EventFQPWorkfile contain the temporary file name that the Version Manager web server is working with instead of the workfile name as seen in the Version Manager web client.
If a check-in operation prompts the user for additional information, such as whether or not to continue checking in an unchanged workfile, then the Unconditional PrePut Event Trigger fires twice if the user allows Version Manager to complete the operation. Event Trigger programs affected by these characteristics may require modification.
If the event trigger puts up a dialog box, it is actually displayed on the server, not the client. If the dialog box is modal, it stops the Version Manager web server from processing any further requests from all users until the dialog box is closed.
If your browser is configured to prevent pop-up ads, the Version Manager web client may not work correctly. Either turn off the pop-up blocking feature, or add the Version Manager server to the list of sites that are allowed to display pop-up windows.
If one, or more, servlets are defined for the Version Manager Web Server Application (this provides access for the Version Manager Web Client), and the associated project databases are on a Version Manager File Server, then all File Servers containing repositories used by these components must be defined on the server(s) through which the Web Client users connect--including the File Server itself (as "localhost" or using its server name). To do so, see the File Server chapter of the PVCS Version Manager Administrator's Guide.
|
Part 4: Version Manager WebDAV Server |
(Windows 7 only) The Digest Authentication mechanism used by the Version Manager WebDAV server is not compatible with the Microsoft WebDAV Mini Redirector. To work around this issue, see this Knowledgebase support article:
http://knowledgebase.serena.com/InfoCenter/index?page=content&id=D21501
If you are able to connect to WebDAV Server but encounter problems working in a WebDAV client, the client may have WebDAV issues.
We recommend that you:
Go to the client support web site and install any recommended service packs. Search the client KnowledgeBase or support documents for reported WebDAV problems and fixes.
Check the KnowledgeBase for articles about specific client problems and fixes.
Some WebDAV clients (e.g., Dreamweaver) may require you to enter a password for authentication. We recommend that you have a Version Manager password so that the WebDAV clients will work properly. If you do not have a Version Manager password, define one using the Version Manager desktop client.
To troubleshoot connection problems with WebDAV Server, first check the Tomcat server console for any errors or exceptions.
If you do not see any errors, do the following:
Check that you can access the Version Manager project database by logging in to Version Manager. Note that you should verify the project database specified in vm.properties.
Check that the web server is up and running by entering the web server URL in your web browser. For example: http://Test1:10070/
Check that the Tomcat web server is running by entering the Tomcat URL in your web browser. For example: http://Test1:8080
Check that the DAV servlet can be accessed from a supported client, such as web folders, by connecting to Tomcat directly from the client. For example: http://Test1:8080/SampleDB.dav.
If you can't access the servlet, check the Tomcat server console for any exceptions.
If the DAV servlet can be accessed by a client directly through Tomcat, try adding a web folder using the web server (e.g., Apache or IIS) port number. For example: http://Test1:10070/SampleDB.dav
If this does not work, then the problem is with the web server configuration. Check the Tomcat and web server logs to identify the errors.
Check that the web server is using the right port setting to communicate with Tomcat. Open the following two files:
VM_Install_Dir/vm/common/tomcat/conf/jk/workers.properties
VM_Install_Dir/vm/common/tomcat/conf/server.xml
Verify that the port setting for worker.ajp13.port in workers.properties matches the port specified in server.xml under "Apache AJP13 support."
If the port settings do not match, change them so they are the same.
The workspace setting for default version (a label) determines which files are visible through WebDAV Server. Unlike the Version Manager desktop client, WebDAV Server only shows the files that match the default version setting. If a default version is not set, then the default is the tip revision of the trunk. In this case, only these tip revisions will be visible through WebDAV Server.
After successfully connecting to WebDAV Server, most failures on common operations (e.g., check out or add workfiles) occur due to lack of privileges.
NOTE: To be able to create new archives through WebDAV, users must be assigned the Add Version Label privilege in addition to the Create Archive privilege.
Log in to Version Manager as that user to verify that you can perform the operations allowed with the specified privileges. If you can perform the correct operations in Version Manager, you should be able to perform them using WebDAV Server.
If you change a user's privileges, those changes are not visible to the user until you restart Tomcat or the user's current session times out.
To ensure that the Euro character works properly on Solaris, do the following:
Install the latest OS patches for Solaris.
In the Solaris Login dialog box (console), click Options and then select Language | en_ISO8859-15.
Log in; then start WebDAV Server by running ./pvcsstart.sh from VM_Install_Dir/vm/common/bin.
Part 5: Copyright/Disclaimers/Support |
To obtain product support, log into portal.microfocus.com.
The license information for Third Party components used by and distributed with PVCS Version Manager can be found in the PVCS installation directory.
End Readme
Copyright © 2003–2024 Micro Focus or one of its affiliates.