The Assign Component Privileges window lets you assign privileges for specific components to particular users.
- Select one or more users and one or more components
The Omnis VCS is not available in some editions of Omnis Studio, including the Community Edition, so in this case it will not appear in the Studio Browser.
This chapter describes how you can use the Omnis VCS (Version Control System) to control Omnis application development in a team environment. In such an environment, with several people working on the same application at the same time, perhaps in different locations, you need to ensure that only one person can change a particular component at a time and that any modifications are not lost or overwritten. The Omnis VCS is built into the Studio Browser and therefore provides tight integration with the whole Omnis IDE: specifically, the Omnis VCS allows you to control the development of your Omnis applications (classes and libraries), or any other project involving many different files such as web or Intranet applications, and it allows you to build your Omnis application for deployment to your customers or organization.
The Omnis VCS lets you revise Omnis library files and other application components systematically. Apart from the Omnis libraries and classes within those libraries, you may have your own externals, text files, web components, Html files, and so on, that are all necessary to the running of the application. The Omnis VCS can handle all these types of files and components. The repository for the VCS would typically be a SQL database within your own domain, or on a remote, cloud-based server.
In this chapter, the term component is used to refer to all types of files and different components stored on disk. With regards to the Omnis VCS, a non-Omnis component is any disk file or external component other than an Omnis class.
When using the VCS in Studio 10, you must create a new VCS repository due to the changes in the Omnis language syntax resulting from the new code editor. You are advised to open and convert your library, then check the conversion logs to look at any possible issues in your code (any conversion issues are shown in the Find and Replace log, and written to a log file in the ‘conversion’ folder in the logs folder). Then when you are satisfied your library and its code are OK, you can check the classes in your library into a new VCS repository created in Studio 10.
There is no change in the structure of VCS repositories from Omnis Studio version 5 to version 6, but if you are upgrading to Omnis Studio 6/8 or above from a version prior to version 5, you cannot use your old VCS repositories. In Omnis Studio version 5 there were a number of significant changes to the structure of the VCS which means repositories created in versions of Omnis Studio prior to version 5 will not work with Omnis Studio 6/8 or above.
Existing VCS repositories created in versions of Omnis Studio prior to version 5 must therefore be re-created in Omnis Studio 6/8 or above to ensure that they are in the new format. To do this, you must do a build of your existing project (or projects) using your old version of Omnis Studio, create a new VCS repository in Omnis Studio 6 or above, and check in your project(s) and components into the new Studio 6/8 repository. You will also need to setup all user accounts and preferences in the new repository.
Project branching was deprecated in Studio 8.1 and you are no longer recommended to use branching in VCS projects. For backwards compatibility in branched projects only, support for branching is available by setting the enableBranching item in the ‘vcs’ section of the config.json file to True.
In addition, sys(236) returns true if VCS branching is enabled. If sys(236) returns false on a branched project, the VCS will display the default branch data.
To place Omnis libraries under version control you check them into the Omnis VCS from the Libraries tree in the Studio Browser, or for non-Omnis components from the File Browser in the VCS itself. All the components you check into the VCS are kept in a project. The VCS stores each project in its own repository database, which can be a server database within your own domain or a remote location To use the VCS you must first create a database session to store your project: see below.
The Omnis VCS provides all the functionality to set up, manage, and use version control, including:
Creating a database session and VCS repository
Checking in Omnis libraries and other non-Omnis components
Creating a project
Managing and supervising users
Building projects and libraries for distribution
Managing projects and granting user privileges
Setting VCS options
The Omnis VCS is permanently available in the Studio Browser (unless you’re using the Community edition). The IDE Options option in the Hub in the Studio Browser lets you hide or show the VCS; if for some reason the VCS is not visible in the Studio Browser you can enable it in the Hub.
To use the VCS, click on the VCS option in the Studio Browser. The Session Manager and the Open Session options are shown in the Studio Browser which allow you to setup your VCS repository.
The VCS tree displays all your open projects and works in a very similar way to the Libraries and SQL Browser tree. The VCS context menu lets you open and close sessions, and perform user administration functions. When you select a project in the VCS, the Browser shows the contents of that project.
You can create a VCS repository in an Omnis data file, but this is only provided for backwards compatibility with legacy applications, therefore this option should not be used for new applications or projects.
This section is for the lead developer or manager in the development team and describes how you can setup a VCS repository and create a new project containing all your application components.
To use the VCS, you need to connect to a database via a session, set up the Supervisor user, and create a VCS repository. You can open a VCS session using the SQL Browser, but you should use the VCS session browser for convenience.
You can create a VCS repository on a server database such as PostgreSQL, available in all versions of Omnis Studio, or using one of the many other leading databases such as Oracle, Sybase, MySQL, and so on. You can access a repository using a native DAM for the chosen database, or you can use ODBC.
Once you have connected to your database, the VCS operates in the same way, regardless of the database and the location the repository is stored in. To setup a new project, you need to:
Define a new database session, and create a new repository
Sign in as Supervisor (default password is password), then create and define users
Check in your libraries, classes and other components (the check in process creates a new project for you) and assign access privileges to components for individual users
You also need to tell the members of your development team their usernames and passwords, and provide them access to the VCS repository
If you are using Sybase for your VCS repository, you must make sure the transaction log has enough capacity to handle your transactions. See the Sybase documentation for details on the transaction log. You can use the command
dbcc checktable (syslogs)while you are running the VCS against your repository to check the status of the transaction log. You must also set the option “select into/bulkcopy” to false with the following remote procedure call
sp_dboption <db>, “select into/bulkcopy”, falsewhere <db> is your Sybase database name. The VCS issues an error message and aborts logon if the target database has the “select into/bulkcopy” option set.
To create a new VCS session, you can either use the default session, called ‘VCS_Session’, or create a new one.
To create a VCS session
Select VCS in the Studio Browser and click on the Session Manager option
Click on the New Session option
The Modify Session dialog opens which allows you to enter the details of the new session.
To duplicate a VCS session
If you have a session that is a suitable template for a new one
In either case, a new session appears in the VCS Session Browser. You can now click on your session and modify it.
To modify a VCS session
or
The Modify Session dialog lets you modify the details of the selected session; it is identical to the session definition dialog in the SQL Browser.
Note that to make a session usable with the VCS, you must select VCS from the Session type dropdown list.
The information you need to supply depends on the database you want to use, but would normally include hostname, username and password, plus you need to select the correct DAM for your chosen database, which will depend on your version of Omnis Studio.
To open an existing VCS session
Select the VCS option in the Studio Browser, click on the Open Session option and select the session from the list of VCS sessions
Enter the Username and Password to open the session
You can specify that a VCS session logs on automatically when Omnis starts. On the Modify session dialog there is a ‘VCS’ tab that allows you to enter the VCS username and password which will be used to log onto the VCS automatically when you start Omnis. If this is an existing session, there is a button which allows you to verify the username/password are correct for the session. Then on the Session Definition tab you need to enable the ‘Logon at Startup’ option.
The VCS stores times in UTC (Co-Ordinated Universal Time) but displays times using your local time zone, which is set automatically.
When you create and/or open a VCS session, you must log on to your database and sign into the VCS as the Supervisor user. The VCS logs on to your database and checks for a repository. When you open a VCS session for the first time, a VCS repository will not be found, and the VCS prompts you to add certain VCS resources or tables. If you click on the No button, the log on process is aborted. If you agree, certain VCS tables are installed so the repository is available for use, and a user called Supervisor, with password “password”, is set up automatically.
Once logged on to the repository, the Supervisor has access to an option from the VCS context menu titled “Remove Repository”, this option will remove all the tables created by the VCS.
To sign into the VCS for the first time
When you log on to your VCS repository, the Sign in window appears. When you logon for the first time you need to sign in as Supervisor.
Both the username and password are case sensitive, so make sure both words are in the correct case, otherwise you will not be able to logon.
To ensure a secure system, you should change the Supervisor name and password. You can do this later, but to do it now
The User Administration window lets you add and remove users, and initially displays only one defined user, Supervisor. The columns in the list show details about each user, in this case the Supervisor, including the user's name, password, phone extension, department, and status.
Change the “Supervisor” username to your name and enter a new password
Enter any more information you wish to store, and click on the Finished button
As a Supervisor, you can allow other users to have Supervisor status so they can create and delete users as well. You will also need to set up the regular users who will check components in and out, and set up preferences.
User administration involves managing the users of a project and assigning them privileges for the components in the project. Before developers can start using the project, you need to add each one as a project user and grant the right privileges for the components they need to change.
Once you sign into the project as Supervisor, you can add, alter and remove users of the project. The User Administration window displays a list of existing users. The Supervisor can add any number of additional users and assign the following privileges which determine the extent to which a user can access components:
Observer
can see components only, therefore user cannot check components out or in
Participant
user can check components out and in, but cannot perform user admin
Supervisor
can do everything, including adding or deleting users and changing user details, and checking components out and in
Only a Supervisor can see a user’s password. Only the first Supervisor user can grant Supervisor status to other users.
To add a new user
Click on the User Admin option and click on the Add User button, or you can right-click on the list of users and select Add User
Add the new user information, including the username and password; you can add the phone extension number and department name for the user as well
Change the type of user as appropriate; a new user is set to Participant by default
Click on the Finished button and you are prompted to Save the Changes
To change an existing user’s definition
Select the user in the list and change the user details,
Click on the Finished button and you are prompted to Save the Changes
Do not change the status of the Supervisor user, particularly if you have only one user with Supervisor status. If you change the status of the Supervisor user you will no longer be able to manage the project and its users.
To delete a user
Select the user in the list and click on the Delete button
Click on the Finished button and you are prompted to Save the Changes
The final step in setting up your project is to check the components in your application into the VCS. You can check in complete Omnis libraries to include all the classes in those libraries, you can check in individual classes from any number of different libraries, and you can check in a whole folder hierarchy containing all the necessary files for your application. Once you have checked all the components in, other users can build a local working version of your library or project using the Build Project option.
When you check in your library classes and other components for the first time a new project is created for you automatically. Using this check-in method creates a new project with the same name as your library. Alternatively, you can create a new project using the ‘New Project’ option in the VCS window, although this is not necessary if you start by checking components into the VCS.
All developers working on a project should have access to all the Omnis classes in your library. Therefore, you should check in all the necessary classes in your library, including any system tables, superclasses, and task classes. The system tables contain information about the fonts, display formats, and so on, used in your library. In particular, if the objects in your library use field styles you should remember to check in the #STYLES system table. You can use the Class Filter option (press F7/Cmnd-7) in the Studio Browser to make sure all the classes in your library are displayed. In future, if you change the system tables in your local library you must remember to check them back into the VCS along with any other classes you may have changed. You should not check in the #DEBUG system table class that may appear in Omnis; this exists temporarily for internal use only.
To check an Omnis library or individual classes into the VCS
If you want to check in individual Omnis classes
or you can
Whichever method you choose, the Check in components dialog appears. This dialog lets you set the check in options for the selected components. If you check in a library all the classes in the library are checked in automatically.
When you check in classes or libraries for the first time they are set to read-only, so they are protected before the first build has been performed. You can control this behavior on the Check in tab in the VCS Options (right-click on the VCS node in the Studio Browser).
The version string for each component is currently set to “1”. You can enter a special version in the Version field if you want to use a different numbering scheme, although this is not recommended. All the components in the VCS have both a version and a revision number, each of which is an integer value. The version indicates the major revision or release of a component and typically applies to all the classes in the library, so it’s effectively the version of the library. The revision number indicates a relatively minor change to the component. When you first check in a component, you can assign it a version; the VCS automatically sets this to 1 and the revision number to 0. Each time you check in a component, the VCS assigns a new revision, but the version doesn’t change unless you change it explicitly in the check in dialog.
A progress bar shows the number of components added. When all the components are checked in, the project appears in the VCS tree, with the same name as your library.
The VCS will prompt you if you have not activated the Options and Notes tab when checking in/out. You can manage this behavior on the VCS Options, Check Out & Check In tabs using the new "Prompt for Options and Notes" option.
The VCS checks in external components without the file system folders being created within the repository. The old behavior (pre-Studio 10) can be restored by unchecking the Check-In preference "Ignore file system folders for external components".
You can use the Omnis VCS to control most other types of non-Omnis components such as external components (DLLs or plug-ins), documents, Web pages, PDF files, Omnis data files, and so on. You can use the Omnis VCS to manage any type of project containing any number of files, including ones that don’t contain Omnis libraries or classes.
To check in non-Omnis components, you use the File Browser available within the VCS itself.
Important Note: You can check Omnis library files into the VCS using the File Browser, but this is only appropriate if you want to manage the library as a discreet disk file. However, if you want to access all the classes in the Omnis library, you should check the library into the VCS as separate classes, as described in the previous section, and not using the File Browser.
To check non-Omnis components into the VCS
Select your project under the VCS node in the Studio Browser (not in the right-hand pane)
Click on the File Browser option
Locate the files or folder you want to check into the VCS using the Select Files/Folder button
From thereon, the check in process for non-Omnis components is exactly the same as for Omnis classes, that is, the Check in components dialog appears which lets you set the check in options for the selected components.
If you check in a folder, all the files and all subfolders and files within that folder are checked into the VCS. In this case, you could, for example, check in a complete folder & file structure containing your own Help system.
To see the contents of a project
You may find the Details view most useful when viewing the components in a project, since that view shows information such as the version, the status, which user has checked each component in or out, and so on. You can change the view using the View menu on the main Studio Browser menubar. In addition, you can sort the contents of your project by clicking on one of the column headers in the VCS Browser.
You can create folder classes in an Omnis library to allow you to store and organize the classes within the library. When you check a library into the Omnis VCS these folder classes are copied into the VCS project. It is also possible to create a folder class directly within a VCS project via the hyperlink option ‘New Folder’ available at the VCS project level. This will allow you to organize the classes in your VCS project, but will also allow you to organize non-Omnis objects such as external components.
Depending on how a project folder is created and what it contains, it can have one of three possible states:
a "normal" folder is one that is generated within an Omnis library and contains only Omnis classes
an "external" folder is one that is generated from within the VCS
a "hybrid" folder is one that contains both Omnis classes and non-Omnis Objects
When you build a project, normal folders will be built in the destination library. External folders will be built into the file system using the folder name as a directory appended to the build path with any non-Omnis Objects built there. A hybrid folder will build a folder class in the Omnis library along with any Omnis classes inside it as well as building to the file system.
If you move a non-Omnis object to a folder class that was previously generated from an Omnis library (a normal folder), that folder will become a hybrid folder. The same thing will happen when you move an Omnis class to an external folder.
Note: Once a folder has become a hybrid, it will remain one: Therefore empty folder classes may be generated when building a project even if you have deleted all classes from the folder.
It is now possible to hide the folders within a VCS project thereby giving you a flat view of all the components in your project. This may be useful when you want to quickly locate a class rather than navigating the entire folder structure in your project.
To hide or show the folders in your project, click on the Hide / Show folders hyperlink option in the VCS Browser.
When you have checked in all the necessary components into your project, you need to assign access privileges to each component for each user.
To grant component privileges
Select the set of components for which you want to grant the privileges
Click on the Privileges option or right-click on the component(s) and select the Privileges option from the context menu
The Assign Component Privileges window lets you assign privileges for specific components to particular users.
The Assign Component Privileges window lets you assign privileges for specific components or all classes within a folder to particular users. Classes or folders can be selected or deselected individually. The second pane lists all the privileges that have been set for the current project. In addition, you can set privileges at a project level using the hyperlink or context menu options. Note that when these options are used, the tree only shows the project name, not the individual classes within it.
Alternatively, you can check the ‘Assign privileges when checking in for the first time’ option under the Check In tab on the VCS Options dialog to ensure that all users are granted access to all components in your project automatically when you first check in the components.
For more details about assigning privileges to components see the Managing Components section.
This section is for developers who wish to check out components from the VCS and start working on their application. Lead developers or managers (Supervisors) wishing to setup a VCS repository and create a new project should read the beginning of this chapter.
Once the Supervisor has created a project, set up the users, checked in classes and granted access to components, users or developers can start using the VCS. Assuming you have ‘Participant’ user status, you can:
Sign in to the VCS
Check out one or more components that you need to work on
Check those components back into the VCS once you have finished with them
To sign in to the VCS as a user
Click on the VCS option in the Studio Browser
Click on the Open Session option and select the appropriate project in the list
Enter your user name and password
If you don’t have a valid user name and password, you can sign in as a temporary user by checking the Observer check box. An observer can view information about the components stored in a project, but cannot check components in or out, or perform any other VCS tasks. Alternatively, you can check the Create User check box to create a new user and password, which signs you in with Participant status. The Supervisor can change your user status at a later stage if required.
When you check out a component into a local library, it becomes locked in the VCS, preventing other users from checking it out. A locked component is shown in the VCS with a lock icon. Alternatively, if you copy out a component it is not locked in the VCS and other users can check it out if they wish. When copying out a component you can change it in your local library, but you cannot check it back in to the VCS. In practice, copying out is a convenient way of viewing components locally without locking them in the VCS.
You can check out or copy out multiple components at the same time, but they must all be Omnis classes or all non-Omnis components during a single check out process. Components may have the same or different target libraries or folders.
To Check out or Copy out components
Display the components in your project by double-clicking on the project in the VCS Browser, or selecting the project name in the VCS tree
Select the components in the VCS Browser that you want to check out or copy out
Select the Check Out option, or right-click on the component(s) and select the Check out option in the context menu
or for Omnis classes only
Drag the classes from your VCS project and drop them on the appropriate library in the Libraries node in the Studio Browser
In the Check out dialog, select either Check Out or Copy Out and whether the component should overwrite an existing one or prompt for a new name (you can change the default for both these options in the VCS Options)
You can add a description for the checking or copying out process
You can add a separate note for each component by clicking the Expand Notes button.
If the VCS cannot locate the original library for an Omnis class, it will prompt you to select a target library. You should select a library, or skip this component. The VCS may prompt you to locate a library for further classes. For non-Omnis components the VCS prompts you for a destination folder.
If you check out an Omnis class that has a superclass or belongs to a design task, read-only copies of the superclass(es) and design task are copied out, assuming the ‘Automatically copy out related components’ preference is enabled in the VCS options.
In the Libraries tree, Omnis classes are shown as checked out with a lock icon.
You can check out a class from the VCS directly from the Find & Replace log window, assuming the class is not already checked out. You can select a line or multiple lines in the Find log, right-click on the selection, and select the Check Out option. You will be prompted to log onto the VCS if required and the Check-out dialog will be displayed containing the selected classes ready to be checked out.
The “Checked Out Classes” option in the main VCS browser opens a list showing all the classes that are checked out by the current user, or for the Supervisor user, the window shows a list of checked out classes for all users.
When checking out a class, you can update the destination library properties with the properties that are held in the VCS for that project. This is especially useful for situations in which there are multiple developers working on the same project. You can enable this feature by checking ‘Update the destination library with preferences from the VCS’ option on the Check Out tab of the VCS Options.
You can maintain the superclass or design task library name for checked out classes by enabling ‘Maintain superclass / design task library name’ option on the Check Out tab of the VCS Options. In this case, the superclass (or design task) library name is not removed from checked out classes. This is necessary when the superclass exists in a separate library and there is a class with the same name as the superclass in the current library.
There is a hyperlink option in the Libraries view of the Studio Browser “Show Checked Out” to display only checked out classes in the current local library. Once enabled you can click the option again to show all classes.
When you have finished making changes to a class or component in your local library, you need to check it back into the VCS. This unlocks the component in the current VCS repository and allows other users to check it out and make changes or propagate your changes into their local libraries.
Checking in a component releases its lock and makes it available to other users for checking out. The VCS stores the changes in its repository and updates the revision number. You can see the current version and revision by clicking on a component and clicking the Information option when the component is selected.
You can also unlock a component without checking in a new version to make it available for other users. You could do this if you decide you don’t want to make any changes to a component after all, or if someone else needs to make immediate changes to a component that you have checked out and is currently locked. In the latter case, you can unlock the component, and check it out again when the other user has made their changes. You can unlock selected components by clicking the Unlock option when the component is selected.
To check in Omnis classes
Select the component(s) in your local library in the Studio Browser
Drag the selected component(s) on to the appropriate project in the VCS Browser
or
To check in non-Omnis components
Assuming your project is selected in the VCS, click on the File Browser option
Locate the folder containing the files your want to check into the VCS
For all types of component, the Check in window appears which lets you set the check in choices for the selected components, as already described in the 'Setting up a Project' section.
You can select one of the following check in modes
Add new revision
adds the component by incrementing the revision number by one, unlocks the component, and updates the check in date, time and other status information
Add new component
adds the component as a new one, setting the version to 1 and revision to zero, by default
The After Check in option lets you decide whether to
Keep checked out
adds the component to the VCS and locks it; in effect, this allows you to backup your components but keeps the component(s) checked out and available for you to make further changes
Delete local copy
adds the component to the VCS and deletes the local copy
You can enter a new version in the Version field or accept the default, and regardless of the check in mode, the VCS sets the version to that number.
You can view only the checked-out classes in a VCS project. To show the Checked Out classes in your project, click on the Show Checked Out hyperlink option in the VCS Browser. To show all classes click on the Show All Classes option.
This option may be useful when you want to quickly identify all the classes that are checked out from a project, and you can combine this option with the ability to hide/show project folders, as above, to view all checked out classes within folders.
When only the Checked Out classes are showing you can select one or more classes, right-click on them and select the Check-in option. You can also run the Class Comparison tool from the same context menu. If there are classes that belong to more than one library, or if a library is not open, these options are disabled.
The Omnis VCS lets you build a project on your local workstation, or any other destination, from the components stored in the VCS repository. You can do this at any time using the Build options in the VCS. You can also build projects at a specific time and date using the ‘Scheduled Build’ option, which is described in the next section in this chapter.
Building any type of project from the VCS guarantees that all the components in your local copy are up-to-date. In the context of Omnis application design, building a project means creating a library containing up-to-date classes for you to work on or test. If your Omnis application contains multiple libraries, doing a build from the VCS guarantees that your whole application is up-to-date. You can also build a project containing non-Omnis components and reproduce the original folder hierarchy required in your application. Using the revision labeling features, you can build previous versions of a library or project for comparison, troubleshooting, or debugging.
When you build a project that contains classes from more than one library, the VCS copies all the components to a single library by default. However by setting the Build options you can build classes to separate libraries, thus maintaining your original library structure.
You can update a local copy of a library in the Studio Browser using the ‘Update from VCS’ option. This is appropriate for updating single libraries, but is not appropriate for building a complete project. The Update from VCS option is described later in this chapter.
To build a project with multiple libraries
Select the VCS in the Studio Browser and click the Options option
Click on the Build tab and check the ‘Maintain Project Structure’ option; this will ensure your project builds to multiple libraries where applicable
To build a project
Whether or not you are building to one or more libraries:
Select your project in the VCS Browser
Click on the Build Project option, or right-click on the project and select the Build Project option from the context menu
The Build Manager lets you configure the project build in detail. It contains one line only if you have chosen to build a project containing Omnis classes into one library, with the project name as the library name. If you have set the preference to maintain your library structure, the Build Manager lists each separate library in the project. If your project contains non-Omnis components you can enter the name and path of the target folder.
You can name the output library using the Label and Build As options:
Label
lets you select the version of the library that you want to build; see the Labels section below
Build As
lets you select the name of the output library
You can set the following options for the output library:
Use Locked and Unlocked folders
if set, you can use locked folders, otherwise if the option is unchecked, all folders and libraries are unlocked
Locked and Unlocked
if set, creates a locked and unlocked version of your library
Locked
if set, the build process creates a locked version of your library preventing other users from seeing or changing the contents of the library; checking the Locked check box option locks the whole contents of a library but you can lock individual classes using the Lock Classes window.
To lock individual classes, uncheck the Locked option, right-click the project in the Build window, select the Lock Classes option, and select the classes you want to lock in the popup window. Note you can also lock folders, which will lock the whole contents of the folder
Multiple Build Paths
when checked, you can select separate build paths for each project using the context menu on the project list
Strip Comments
removes comments from your Omnis code, as well as variable & file descriptions; also enables the class selection context menu; see the Remove Comments section below
Overwrite
if true, overwrites all the components in the target library or folder, that is, the VCS removes all the classes in the target library and completely rebuilds the library. Otherwise if the option is unchecked, the VCS updates only the components that are different from the current library or project. This is useful for quickly bringing an existing library up-to-date with the current checked-in classes in the VCS
Lower case
ensures the library name is in lower case
Type the path for your library or project in the ‘Build into’ field or use the Browse button to select a folder or create a new one
When you have set the options for your project, click on the Build button
The VCS opens the Build Results dialog showing the progress and status of the build. The VCS creates a log file for the build and displays it at the bottom of the build window.
You can exclude specific classes from a build. The context menu on the project class list includes the option "Exclude Classes" which allows you to select classes you do not wish to include in a build.
When you create a build from the VCS, you can remove the comments from the code in your libraries by checking the ‘Strip Comments’ check box. If the option is set, all comments within methods are removed, as well as all variable definitions, and descriptions for file, query, and schema classes. This will make library files smaller, which may be better for deployment.
You can select classes that you want to retain their comments when you build a project. To do this, right-click on the list of projects in the Build Window, select the ‘Do Not Strip Comments’ option, and select the classes in which you want the keep comments.
Under the Build tab in the VCS Options window, there are four checkboxes that, if checked, will ensure that comments in variables, file classes, query classes and schema classes are retained.
When you create a build from your Omnis VCS repository, the project may contain classes or objects that are checked out of the current repository. If you proceed with the build, your project may not contain the most up-to-date classes. In this case, you may want to look in your project before building the project to ensure that all the classes in the project you want to build are all checked in.
If the ‘Warn if there are classes checked out’ option is set (in the VCS Options), the VCS will warn you that the build contains classes that are checked out. In this case, a window will open listing all the checked out classes with an option to proceed with the build or cancel it. To build a completely up-to-date copy of a library, you should ensure that all classes are checked into the VCS before proceeding with a build.
When you build a library, the VCS includes the system tables by default, assuming you have copied them to your project. The system tables contain library-specific settings such as fonts, input masks, field styles, and in the case of #ICONS the icons in your library, so they are important in maintaining the correct look-and-feel and behavior in your application. Remember that when you check in a version of the library, the VCS does not automatically put the system tables into the library; you must specifically show and select them in the Studio Browser just as you do the other classes in your library.
The Omnis VCS allows you to build projects at a specific time and date, which for large development teams may be useful if you need to build a library out of office hours. You can set up a Scheduled Build from the ‘Scheduled Build’ option in the main Omnis VCS Browser. When you select this link, the Build Manager will open containing a new button called ‘Schedule…’, which opens the ‘Schedule Build Process’ window.
The Schedule Build window allows you to control the frequency of the builds and set the time that you want the build to run. The following options are available:
Never
no scheduled builds occur, but you can still build a project manually
Daily
the build will occur every day at a specified time
Weekly
you can specify which day(s) of the week the build should occur during the week; you can also set the time
Monthly
the build will occur once a month, on the specified day of the month; you can also set the time
The best time to schedule the build is when there is no one else logged on to the VCS. You must ensure that Omnis Studio is running at the time of the build and that you are logged on to the correct VCS repository. If you do not have Studio open at the time of the build schedule, when you next log on during that day, the VCS will prompt you that you have missed the scheduled build and ask if you want to run it then. For example, if you have the build set to run at 7am on a Monday, but do not start Omnis until 8am, Omnis will remind you about the build that you missed.
You should use the ‘Build Manager’ window to define the projects you want to build and how you want them to be built using the normal options that are available. When you click the Finish button these preferences will be saved and the timer started according to the schedule defined.
You can choose to label the build either at the time you schedule the build or when the build runs. Note that if you select ‘Label at Build’ and there is already a label with that name, the VCS will redefine the label with the current state of the classes. This may or may not be what you require, so caution should be exercised, particularly if you are setting the build to run every day and therefore you may lose the ability to rebuild to a specific point in the project development at a later point in time. If you select ‘Label Now’, the VCS will prompt you if there is already a label defined and give you the chance to confirm that you want the label redefined.
You can specify whether the VCS builds a locked or unlocked version of your library (or both) using the Library Status dropdown list in the Build window.
If you have selected a path to save them into, the build notes will be saved to a file prefixed ‘AutomaticBuildNotes_’ within that path. By default the path is the BuildFolder within the main Studio folder.
In long-term projects, the components in your project may undergo many revisions. The VCS tracks these revisions using labels. You can reproduce a particular version of a library using the appropriate label. A label is a string of up to fifty characters that you can assign to a project and each of its components. When a project is complete and you want to release it, you can assign a release name by labeling the project. You can see the label for a project or individual component in its Information window.
To label a project
Select the project in the VCS Browser
Click on the Label Project option, or right-click on the project and select the Label Project option from the context menu
Type in the label and click OK
Once a project has been labeled, the last label assigned is shown in the VCS Project Browser if the browser is in Details view.
When you build a project, you can use labels to select either the latest version of all the components, or an older version. You can also check out a specific revision of a component using its label. See the description of the Check Out process in the section on Managing Components below.
If you delete a component that has a label, it remains in the VCS. If you build a project using that label, the VCS finds and includes the component in the build even though you have deleted it from later revisions of the project. The VCS does not include the component in any builds or labels that occur after you delete the component. For example, if you label a project and its components on Monday, delete a component from it on Tuesday, and do a build on Wednesday using Monday’s label your library will include the component. However if you do a build on Wednesday using the most recent project label, your library will not include the component you deleted on Tuesday.
When the VCS loses its network connection, the list of classes and all hyperlink options are hidden and replaced with a Refresh option (previous versions may have issued numerous messages when a connection was lost). Pressing Refresh will poll the database to see if the connection has been restored, but if the connection is still down an error message will be shown. Polling the database may still result in a wait of several seconds before the connection is restored or any error message is shown.
The Find Class option in the VCS Browser lets you search for a class within the current VCS repository.
The Find Class option in the VCS Browser lets you search for a class within the current VCS repository. When the VCS treelist or list pane is active in the browser, you can press Ctrl-F to open the Find Class window.
You can search for a class within one or more projects. A list of matching classes is displayed, and you can double-click a class to display that class in the appropriate project.
The ‘Update from VCS’ option, available in the main Studio Browser, allows you to bring a local library up to date with the latest version of the library in the current VCS repository. If you have large libraries and multiple developers, you may find this a quick way of ensuring that a local copy of a library has all the changes made by other developers.
To use this feature, select a library in the Studio Browser and click the ‘Update from VCS’ option. Providing that you have a VCS session open and that there is a project in the VCS repository that matches the name of the current local library, this option will bring up the checkout window (in Copy Out mode only) listing all the classes that have a newer class modified date in the VCS than your copy of the library. It will also list all classes that have been added to the repository that do not exist in your local library. If there are classes which you do not want to update, you can uncheck them in the checkout window.
The 'Update from VCS' option is also available at class level in the Studio Browser. In this case, you can select one or more classes or folders, right-click on the selection and select 'Update from VCS' to update only those selected class(es) or folder(s) from the VCS.
The 'Update Local Library' option in the VCS allows you to update the local library with latest changes from the current project. It is the equivalent of the 'Update from VCS' option except that it pushes any updates in the VCS repository to the relevant local library.
When you try to modify a class in a library built from the VCS, it is only possible to edit the class when the class is checked out. If it is not possible to edit the class, the class is considered to be ”read-only“.
If a library has a non-empty VCS build date, then all class editors behave in a read-only fashion, when $showascheckedout is kFalse for the class being edited.
You can disable this behavior using the $alloweditifnotcheckedout Omnis preference ($root.$prefs) which is set to kFalse by default. Set it to kTrue, to disable this behavior.
When this behavior is enabled, new classes in a library with a non-empty VCS build date (created in any way), are automatically marked as checked out.
Replace will not work against a read-only class, an error is written to the find and replace log.
Note that this does not affect the notation (although the notation inspector will not allow changes to a read-only class).
The VCS has an extensive array of component management functions, including
Granting user privileges for components
Associating a component with more than one project
Managing revisions of components
Deleting and renaming components
If you are the first user to put a component under version control, you are the owner of that component. To allow other developers access to a component, you must grant them privileges to it. Without the right privileges, other developers can only view and get information about a component as Observers. Supervisors have all privileges at all times.
To grant component privileges
Display the components in your project by double-clicking on the project in the VCS Browser
Select the set of components for which you want to grant the privileges
Click on the Privileges option or right-click on the component(s) and select the Privileges option from the context menu
The Assign Component Privileges window lets you assign privileges for specific components to particular users. You can choose one of the following levels of privilege
| Privilege level | Description |
|---|---|
| Read/Write | the user may check in, check out, copy out, get information on and build libraries with components |
| Read Only | the user may get information on, build libraries with, and copy out a component into a local library, but cannot check out the component nor check it back in with changes |
| Info Only | the user may get information only about a component |
Select one or more users and one or more components
Select one of the levels of privilege and click the Set button to grant the privileges
Assigning the Info Only privilege also revokes existing privileges from a user. Info Only is the default privilege that any user has for a component. The owner of the component must grant the user, including Supervisors, the Read Only or Read/Write privileges necessary for building libraries or changing the component.
By default, the owner of a component starts with Read/Write privileges for that component, and you must have Read/Write privileges to grant privileges for it to other users.
If you select components for which you don’t have Read/Write privileges, the VCS disables the radio buttons and Set button. If you select components for some of which you have Read/Write privileges, you can use the radio buttons. The VCS does not however, grant the privileges to the user(s) on those components for which you do not have Read/Write privilege.
You may decide to use a single component in many projects, such as a custom logon window, or a generic search component. The VCS can associate or link a component with libraries in different projects, storing the component only once, but building it into different libraries when required. You need only revise the component in one place, rebuild the projects, and the VCS propagates the changes to all the libraries that contain the component.
You must have Supervisor access or be the owner of a component to associate or link it with another project or library.
To associate a component with a project
Open the project containing the component, and select the component
Click on the Link option, or right-click on the component and select the Link option from the context menu
The Link option displays a window showing all your open projects (the link window will not open if there are no other open projects, or if the component is already linked to all other open projects).
Select the project with which you want to link the component, or you can open a project in the list and select a particular library
Click OK to link the component
If the Maintain Project Structure build option is not checked, the component is associated with the single library together with all the other components. Otherwise if the build option is enabled, the component is associated with a library of the same name as the one containing it. If such a library does not exist, it is created automatically.
To delete a linked component in a specific project
Open the project containing the linked component
Select the component, and click on the Delete option, or right-click on the component and select the Delete option from the context menu
If the component has a label, it becomes disassociated and a small trash can icon is shown. If you build a project using a label, the component is still available for the build, even though the library or project in question may no longer associate with the component.
When you first check in a component, the VCS creates the component in its repository and sets the version to 1 and the revision to zero. Each time you check in a new revision of the component, the VCS stores the new component and increments its revision number. The sequence of changes to a component is stored in its revision history.
To see the revision history for a component
Select the component in the VCS
Click on the Revision History option, or right-click on the component and select the Revision History option from the context menu
The Revision History window tells you
the version string and revision number
the user who modified the component
the component name
and change notes, if any
The revisions for a component are listed in chronological order with the most recent revision at the top. You can delete old or newer revisions of a component.
If you have Read/Write or Read Only privileges for the component, you can copy out the latest revision of the component from the Revision History window by clicking on the Copy Out Revision button. A list of currently open libraries appears, so you can choose which one to copy the component into. Select a library and click on Select.
If a component already exists in the library with the same name as the copy, the VCS prompts for a new name. Keeping the old name overwrites the existing component; entering a new one renames the copy.
The Project Revisions option allows you to see all the revisions to a project, rather than having to drill down to a class and see the revisions which are only available for that class.
The Project Revisions option is available at the project level as a context menu option in the tree list or via the hyperlinks when clicking in the list of projects. You can filter the revisions from the droplists according to the user who created the revision or a date period. You can also filter by typing in the edit box.
You can drilldown to see which labels have been applied to the revision by right-clicking on it. This window also allows you to compare or copy out in the same way as the class level revision window. You can also select multiple classes to copy out multiple revisions. It is also possible to double-click rather than using the context menu to view the revision data.
All class types now have the $vcsrevision property, which allows the Omnis VCS to determine whether or not classes in a local library are up to date with the latest revision in the VCS repository. The $vcsrevision property is the revision number of the class, and is used for classes stored in the Omnis VCS. It is set to zero if the library was not built by the VCS (i.e. it was created in the IDE), or if the library was built prior to Omnis Studio 10.2.
The property is read-only in the Property Manager, as it is intended for use by the Omnis VCS library, or any custom class editing tools you may have created. It can only be assigned by executing code.
The Update Version option is available on the class context menu to allow you to update the version number of classes, including the ability to reset revision numbers to 0. The option is available to Supervisor level users only.
The Method Inspector lets you examine the methods in a class without having to Check Out or Copy Out a class or build the library. This may be useful if you want to quickly check what methods are contained in a class or what code is contained in a particular method within a class.
To open the Method Inspector, you can select the class and choose the ‘Method Inspector’ hyperlink option in the VCS Browser, or Right-click on the class and select the option from the context menu.
On the first tab of the Method Inspector window, there is a list of all the methods within the class. If the class has a superclass, the superclass methods are also shown. They are displayed in blue to differentiate them as inherited methods.
If the selected class is a window, report, remote form, menu or toolbar, there is another checkbox displayed at the bottom of the list to allow you view field methods. By default this option is not selected except for menu and toolbar classes.
Further properties of the method are shown in this tab: description, execute on client and web service method. There is also a context menu option to allow you to view the path to the method within the class – this is of most use if you are looking at field methods as you can see the exact path to the method.
If you double-click a method, the code for the method is displayed on the second tab. Should the method be inherited, there is a context menu option to allow you to view the superclass code.
It is possible for a component that has a parent folder to lose its parent folder; in this case, the component is regarded as an ‘orphan’ component. A component can lose its parent folder either because the parent folder itself no longer exists, or the id of the parent folder has changed and the component is not aware of the change. The id of the parent folder for a component is stored in its $parentfolder property.
The ‘Find Orphans’ option in the VCS will look for components where their $parentfolder id does not exist and place these components in the ‘Orphans’ folder. You can move the component(s) back to their respective folders or recreate the appropriate folder. In most cases, the option will return no orphan components.
The Component context menu gives you information about a component, and lets you rename, delete, or unlock a component. To open the context menu you must right-click on the component.
To get Info about a component, or rename, delete, or unlock one
or assuming the component is selected, you can
This window displays the information about the component, including the labels, the revision state, the check out history, and links.
To delete a component, you must own the component and it must be checked in. The Delete option checks whether the component belongs to more than one library and whether any labels apply to it. If not, the VCS prompts for confirmation that you want to delete the component. If it does belong to more than one library, the VCS displays a list of associated libraries, letting you choose the ones from which to remove the component.
You can unlock a locked component by clicking on it and selecting the Component>>Unlock menu option. A warning message advises you that having done this, you will not be able to check in a previously checked out version of the component.
To rename a component, you must own the component and it must be checked in. You can rename any component in the VCS, but renaming Omnis classes requires some additional care because of the potential dependencies of some classes on the class you want to rename. That is, before you rename a class in the VCS you must change all references to it in any other classes that refer to the class. You do this by checking out all the relevant classes to the IDE Browser and using the Omnis Find and Replace tool.
To rename a class
Check out the class and any other classes that contain methods which refer to the component
Change the name of the component in the Studio Browser, and answer Yes when you are prompted for whether or not you want to use Find and Replace; this renames the component and changes all references to it in any other components
Check in all the components except for the renamed one
Select the component in the VCS, and click on the Unlock menu option to release its lock
Click on the component again when the VCS has refreshed
Click on the component to rename it
The Compare Classes option in the VCS lets you compare all the classes in two different VCS projects, or it lets you compare individual classes in different projects. It also lets you compare different revisions of the same class. The Compare Classes tool is also available in the Studio Browser and allows you to compare classes in libraries not checked into the VCS.
The Compare Classes tool compares the properties and methods of the specified classes and highlights any differences. Specifically, the comparison tool will compare each line in a method of one class with the corresponding lines in a method of the other class and will highlight even the smallest change or difference between the two classes or revisions.
To use the Compare Classes tool
The Compare Classes tool is also available in the Revision History window to allow you to compare revisions of the same class.
The Compare Classes window lets you load two different versions of the same VCS project or library: you should load the older project or library into the Library/Project A list (on the left) and the newer version into the Library/Project B list (on the right). The context menu on the Compare Classes window (Right-click to open it) lets you switch libraries from List A to List B.
You can compare all the classes in a VCS project or library that have a modified $classdata, which avoids comparing classes that have not changed. The Compare Classes tool shows which classes have a modified $classdata and by default will compare only these classes. You can uncheck the ‘Only include classes where $classdata differs’ checkbox to compare all the classes in a project or library.
By default, the Compare Classes tool only compares any classes that are selected in the VCS. To compare all classes, regardless of any selections in the VCS, you can uncheck the ‘Only include classes pre-selected in the class browser or VCS’ option in the Compare window.
You can use Ctrl/Cmnd-C to copy code from the Differences panel, or use the Copy to Clipboard option in the context menu.
You can set your individual preferences for the VCS using the Options option in the list of options in the VCS Browser. You can set Display, Check out, Check in, Build, and Method Inspector options in the VCS Options window.
To set your VCS options
The Display options let you specify the format of dates and times for the VCS windows and dialogs. The default format is: D m Y H:N:S, such as 12 May 09 14:30:35.
The Check Out options control how components are checked out of the VCS.
Default mode is “Check Out Modifiable” copies
determines whether or not a component is checked out or copied out; the default is for components to be checked out in modifiable mode.
Default replacements to overwrite existing items
determines whether or not an existing component in your target library is overwritten when a component is checked out. The default is that components are checked out and overwritten without warning, otherwise when the option is disabled, you are prompted to overwrite or rename the component.
Automatically copy out related components
relates to Omnis classes that have superclasses and design tasks. If you have a class that is a subclass of another class, and you check out the subclass, this option ensures the superclass is checked out. When this option is disabled the superclass will not be copied out; in this case, you will not see any fields and methods that are contained in the superclass. If this option is set, read-only copies of the superclass(es) are copied out, as well as the design task for the original classes being checked out.
Default to copy out component if already checked out
when this option is set, it forces components to be checked out even if they are already checked out. If this option is disabled, the VCS will warn you that the component is already checked out and prompt you to Copy out or cancel the operation.
Maintain superclass / design task library name
ensures that classes retain the library name as part of the superclass or design task name. The preference is disabled by default to ensure backward compatibility. With the preference disabled, the library name is stripped out at checkout or build time. This means that if, for example, you have ‘LibraryA’ with a class called ‘classA’ which has a superclass ‘LibraryB.ClassSuper’ and there is also a ‘ClassSuper’ in ‘LibraryA’, Omnis would switch the superclass to ‘LibraryA.ClassSuper’ whenever the class is checked out or built. You can check this option to retain the superclass name to avoid this problem.
Update the destination library with preferences from the VCS
ensures that when enabled the preferences of the destination library are updated from those stored in the VCS.
Ignore Checked Out Classes
when enabled the VCS will not copy out a component if it is already checked out.
Prompt for Options and Notes
when enabled the VCS will prompt you for Options and Notes when checking in/out
Show all options without tabs
when enabled allows you to show all Check in/out options in one screen by hiding the tabs
The Check In options control how components are checked in to the VCS.
If Target Component Does Not Exist
controls what happens when you check in a new component. By default, the ‘Automatically add it to the Project’ option is selected and components are added to a project automatically; otherwise if the ‘Prompt for further instructions’ option is selected the VCS asks if you want to add the component to the current VCS project.
When Component Version Number Changes
controls revision numbers for new versions of a component. By default, the ‘Reset revision numbers to zero’ option is selected and revision numbers are set to zero for new versions; otherwise if the ‘Continue to increment revision numbers’ option is selected the VCS continues to increment revision numbers regardless of the component version. (Version and revision numbers are described earlier in this chapter.)
Assign privileges when checking in for the first time
is useful when, as supervisor, you first set up your project. When enabled and you check in components into the VCS for the first time, the component privileges window is opened allowing you to set the access privileges for each component.
Disable automatic library preference changes
If enabled, this option prevents the automatic updating of library preferences from the library containing the classes to be checked in.
Enable version number validation
allows you to disable version number checking when checking objects into the VCS.
Prompt for Options and Notes
when enabled the VCS will prompt you for Options and Notes when checking in/out
Ignore file system folders for external components
when enabled the VCS checks in external components without the file system folders being created within the repository
Show all options without tabs
when enabled allows you to show all Check in/out options in one screen by hiding the tabs
Make library read-only when checking in for the first time
when enabled the library will become read-only after being checked in for the first time
The Build options control builds in the VCS.
Maintain Project Structure
controls whether or not a build retains the library structure of the components within a project. If this option is enabled, components are built into separate libraries mirroring the original library structure, otherwise all the components in a project are built into a single library.
Only create locked and unlocked folders when required
Selecting this option prevents the VCS from generating locked and unlocked folders in the build path unless the Build process needs them.
Warn if there are classes currently checked out
tells you if there are any classes checked out when you attempt to build a project; if you build a project containing checked out classes your library may not contain the most up-to-date version of classes
Do not build empty folder classes
when enabled the VCS will not build empty folders
When Stripping Comments
During a build all comments in your Omnis code are stripped out. When enabled, the ‘Stripping Comments’ options ensure that comments are retained in all Variable definitions (in the Variable pane of the Method Editor), as well as all File, Query, and Schema classes.
The Method Inspector options are as follows:
The Branches options only affect projects that contain branches, so for all new VCS repositories the Branch options will not appear. The Checking in/out options on the Branches tab allow you to set the check in/out preferences for VCS projects that contain branches.
Use Default Branches
If the ‘Use Default Branches’ option is enabled (the default) and the current project has branches, the default branch is used to check out classes when using the context menu in the Studio browser. If the option is disabled, a list of available branches is displayed to allow you to choose the branch from which to check out the class.
Ignore Branches
If the ‘Ignore Branches’ option is enabled (the default), the VCS automatically uses the branch the component has been checked out from. If the component is present in more than one branch, a window is displayed to allow you to choose the branch from which to check out the class or component.
The VCS has a number of reports available to those with Supervisor status. You can access them by clicking the Reports option in the VCS Browser. Users without supervisor status do not have access to VCS reports and will find this menu option is grayed out.
To use the VCS reports
The VCS Management Reports dialog lets you select a report. The Parameters pane and Description field will change depending on the report you click on.
Select a report and set up its parameters
Click on the Print button to generate the report
Select the required destination, and click on OK
Where appropriate, the reports in the VCS will reflect the existence of branches in your projects.
From Studio 11, some of the functions of the Omnis VCS have been exposed to allow you to interact with the VCS or the contents of a project programmatically. You can make API calls to the Omnis VCS by calling:
$root.$modes.$dotoolmethod(kEnvToolVcs,'vcs_method_name'[,parameters,..]),
The first parameter is always kEnvToolVcs to specify a VCS method, followed by the VCS method name and the appropriate parameters.
Each API call requires the use of a token, which is a unique string generated by the VCS when a successful logon occurs. This token is an essential parameter to all the calls (apart from $x_logonVCS) as it is the mechanism that the VCS uses to verify the validity of the API call. By default, a token will last for 60 minutes, but you can extend the token lifespan to up to 8 hours. When the token time has expired, you will be logged off automatically and will need to logon again.
The $x_logonVCS method allows you to logon to the Omnis VCS using an existing SQL session, returning a token which must be passed by the other methods.
Do $root.$modes.$dotoolmethod(kEnvToolVcs,'$x_logonVCS',cHOSTNAME,cUSERNAME,cPASSWORD,nTokenTime,cToken,cErrors) Returns bStatusDo $root.$modes.$dotoolmethod(kEnvToolVcs,'$x_logonVCS',cHOSTNAME,cUSERNAME,cPASSWORD,nTokenTime,cToken,cErrors,rSessionOrSessionPoolRef) Returns bStatusDo $root.$modes.$dotoolmethod(kEnvToolVcs,'$x_logonVCS',cHOSTNAME,cUSERNAME,cPASSWORD,nTokenTime,cToken,cErrors[,rSessionOrSessionPoolRef,cDBName]) Returns bStatuscHOSTNAME, cUSERNAME, cPASSWORD are character strings used to identify the session to log onto. The session must have been previously set up via the SQL Browser Session Manager. cHOSTNAME is the name of the VCS session previously set up and cUSERNAME and cPASSWORD are the credentials that are setup inside the VCS (not the database credentials).
nTokenTime is a value to determine (in minutes) how long the token will remain valid for. If 0 is passed, a default value of 60 minutes is applied; the token time can be up to a maximum value of 480 (8 hours).
rSessionOrSessionPoolRef is an optional reference to a SQL session (e.g. $sessions.MY_VCS_SESSION) or a session pool (e.g. $sessionpools.MY_VCS_SESSIONPOOL). This allows you to logon to a session via code rather than using any defined VCS sessions in the SQL Browser Session Manager. If supplied, the API will attempt to logon using this regardless of cHOSTNAME. If no valid reference is passed, the logon will attempt to use cHOSTNAME.
cDBName is an optional name of a database which you want to use. If nothing is passed in cDBName, the default database will be used. It is only necessary to use this when a valid rSessionOrSessionPoolRef is passed.
If the logon is successful, bStatus will return kTrue and cToken will contain a token generated by the VCS which must be used to authenticate subsequent API requests.
As with all the methods (except Logoff), cErrors will contain any errors.
The $x_logoffVCS method logs out of the current VCS session.
Do $root.$modes.$dotoolmethod(kEnvToolVcs,'$x_logoffVCS',cToken)You need to pass cToken to logoff.
The $x_getTokenInfo method returns information about the token and session.
Do $root.$modes.$dotoolmethod(kEnvToolVcs,'$x_getTokenInfo',cToken,rRow,cErrors) Returns bStatusIf successful, rRow lists the Token, Token Expiry Time, the session name you are logged on to, VCS username you are logged on with, the token timeout in minutes and the Logon time.
The $x_listProjects method returns a list of projects.
Do $root.$modes.$dotoolmethod(kEnvToolVcs,'$x_listProjects',lLibList,cToken,cErrors) Returns bStatusIf successful, lLibList will contain the list of projects that are available in the VCS repository.
The $x_listProjectClasses method returns a list of classes in the specified project, and has the following syntax:
Do $root.$modes.$dotoolmethod(kEnvToolVcs,'$x_listProjectClasses',cLIBNAME,lClassList,cToken,cErrors) Returns bStatuscLibName is the name of the project in the VCS from which you want to return the class list.
If the call is successful, lClassList will return a list containing the following information: className, classType, classVersion, classRevision, status (0 - checked in, 1 - checked out), checkedOutDate, checkedOutBy, checkOutNotes, checkedInDate, checkedInBy, checkedInNotes.
The $x_listClassRevisions returns a list of revisions for a class, and has the following syntax:
Do $root.$modes.$dotoolmethod(kEnvToolVcs,'$x_listClassRevisions',rClassRef,lClassRevList,cToken,cErrors) Returns bStatusrefClassRef is a reference to a class in your local library. If the call is successful, a list of revisions will be returned in lClassRevList.
The first column of this list will contain an ID to identify each class revision. See the $x_checkOut method.
The $x_classStatus method returns the status of a class, its checked out status, who checked it out, and so on.
Do $root.$modes.$dotoolmethod(kEnvToolVcs,'$x_classStatus',refClassRef,rRow,cToken,cErrors) Returns bStatusrefClassRef is a reference to a class in your local library. If the call is successful, the row variable rRow will be populated with the name of the class, its checked out status, who checked it out and when, the date of the last revision and who checked it in, as well as the current revision number.
The $x_checkedOutClasses method returns a list of checked out classes.
Do $root.$modes.$dotoolmethod(kEnvToolVcs,'$x_checkedOutClasses',cUserName,[cLibName],lList,cToken,cErrors) Returns bStatuscUserName is a character string for the VCS user name. The optional parameter cLibName filters the list of checked out classes to the supplied library name. If the call is successful, lList will be a list of classes containing project name, user name, class type, class name, checked out date, check out notes and the original library name.
The $x_isClassCurrent method tells you if a local class is up to date or not.
Do $root.$modes.$dotoolmethod(kEnvToolVcs,'$x_isClassCurrent',refClassRef,cClassStatus,cToken,cErrors) Returns bStatusrefClassRef is a reference to a class in your local library. If the call is successful, cClassStatus will contain either 0 or 1: if 0, the class is up to date with the VCS, or if 1, the VCS version is newer than the local copy.
The $x_checkOut method allows you to check out or copy out a class.
Do $root.$modes.$dotoolmethod(kEnvToolVcs,'$x_checkOut',refClassRef,refLibRef,cToken,bCheckOrCopy,revID,cErrors) Returns bStatusDo $root.$modes.$dotoolmethod(kEnvToolVcs,'$x_checkOut',refClassRef,refLibRef,cToken,bCheckOrCopy,revID,cErrors,cCheckOutNotes) Returns bStatusrefClassRef is a reference to a class in your local library and refLibRef is a reference to the library you are checking the class out to. bCheckOrCopy is a boolean allowing you to either check out (kTrue) or copy out the class (kFalse). If you wish to copy out a specific revision of a class, you can use the ID in the first column of the list returned by $x_listClassRevisions (lClassRevList.vcs_id) in the revID parameter to check out the revision.
refClassRef is a reference to a class in your local library and refLibRef is a reference to the library you are checking the class out to. bCheckOrCopy is a boolean allowing you to either check out (kTrue) or copy out the class (kFalse). If you wish to copy out a specific revision of a class, you can use the ID in the first column of the list returned by $x_listClassRevisions (lClassRevList.vcs_id) in the revID parameter to check out the revision, else pass 0. cCheckOutNotes is a string containing notes to be associated with the checkout.
The $x_checkIn method allows you to check in a class.
Do $root.$modes.$dotoolmethod(kEnvToolVcs,'$x_checkIn',refClassRef,refLibRef,cToken,cErrors) Returns bStatusrefClassRef is a reference to a class in your local library and refLibRef is a reference to the library you are checking in from. The project must already exist in the VCS as it is not currently possible to create a new project using the API.
Do $root.$modes.$dotoolmethod(kEnvToolVcs,'$x_checkIn',refClassRef,refLibRef,cToken,cErrors,cCheckInNotes) Returns bStatusrefClassRef is a reference to a class in your local library and refLibRef is a reference to the library you are checking in from. The project must already exist in the VCS as it is not currently possible to create a new project using the API. cCheckInNotes is a string containing notes to be associated with the checkin.
The $x_labelProject method allows you to label a project.
Do $root.$modes.$dotoolmethod(kEnvToolVcs,'$x_labelProject',cProject,cLabel,cToken,bOverwrite,cErrors) Returns bStatuscProject is the name of the project, cLabel is the label and bOverwrite indicates whether to overwrite an existing label of the same name.
The $x_buildProject method allows you to build a project to a specified folder.
Do $root.$modes.$dotoolmethod(kEnvToolVcs,'$x_buildProject',cProject,cBuildPath,cLabel,bLocked,bOverwrite,bLowercase,cToken,cErrors) Returns bStatuscProject is the name of the project, cBuildPath is the directory to build into, cLabel is the label to use, bLocked indicates whether to build a locked library, bOverwrite identifies whether to overwrite an existing library, bLowercase builds the file name in lowercase.