Oracle Repository Command Line Tool
|
Oracle Repository Command Line Tool |
The Command Line Tool can be used in the following ways:
In interactive mode, you can run a series of commands as an interactive session. You can start an interactive session from the operating system command prompt or, on Windows systems, from the Start menu or from the Repository Object Navigator. For details see Starting the Command Line Tool.
Multiple interactive sessions can be opened.
Interactive mode is a single operating system process. Once a session has been started, you can connect to a repository, execute some commands against that repository, then, if required, disconnect and connect to a different repository.
For details of how to use interactive mode, see Using the Command Line Tool in interactive mode.
In one-shot mode, the Command Line Tool executes a single command at each invocation. In this mode, it must be started from an operating system command prompt. For details see Starting the Command Line Tool.
In one-shot mode, you run the Command Line Tool from an operating system prompt and specify one Command Line Tool command you want to execute. The Command Line Tool executes that single command and exits. Not all Command Line Tool commands are available in one-shot mode; the command specifications for each command specify in which modes the command is available.
If the command you are executing needs a connection or a workarea context to be established, you need to supply details of them in when you start the Command Line Tool.
For information about using one-shot mode, see Using the Command Line Tool in one-shot mode.
There are two ways of executing a series of commands using the Command Line Tool:
For information about executing a command script, see Running the Command Line Tool by executing a command script.
The repository owner can assign each user a number of repository privileges. These privileges specify, for example, whether a particular user is allowed to create or delete workareas, containers or configurations. Other repository privileges specify whether a user can perform certain repository operations (such as setting policies or purging objects), or whether that user can use the various software tools that are supplied with Oracle Repository.
Access to a particular workarea, container or configuration is controlled by the user who owns that item. The user who creates a workarea, container or configuration is initially its owner. That user can grant or revoke access rights (for example, update or delete) for that item to or from themselves or another user. However, the owner of an item always retains administrate and select access rights to it. Users can allocate access rights using the Repository Object Navigator.
Access rights and system privileges determine the level at which commands behave for specific users.
For more details, see the Oracle Repository Online Help or the Oracle Repository API and Model Reference Guide.
The access rights that can be granted on containers or workareas are as follows:
|
Access right |
Allows a user to... |
|---|---|
| Administrate | Grant or revoke access privileges on a repository object. |
| Compile | Refresh a workarea. |
| Delete | Delete an object (or perform force delete or purge if they have the necessary repository privileges). |
| Insert | Create an object. |
| Select | Query an object. |
| Update | Modify an object. |
| Update Spec | Redefine a workarea. |
| Version | Check out/check in an object. |
If a user does not have the Version access right, that user can still modify an object provided that the object is checked out.
The system privileges that can be assigned are of three sorts:
The repository privileges that can be assigned are listed below.
|
Repository privilege |
Allows a user to... |
|---|---|
| MANAGE_WORKAREA | Update, delete and compile workareas. |
| MANAGE_CONFIGURATION | Create, update, delete and purge configurations. |
| MANAGE_CONTAINER | Create, update, delete and purge folders, application systems, packages. |
| MANAGE_USER | Create, update and set user privileges. |
| MANAGE_BRANCH_LABEL | Create, update and delete branch labels. |
| MANAGE_DEPENDENCY | Create, update and delete dependencies. |
|
Repository privilege |
Allows a user to... |
|---|---|
| REGISTER_SCHEMA | Register Oracle schemas in the repository. |
| SET_POLICY | Enable and disable policies. |
| PURGE | Purge object versions (delete checked in object versions). |
| FORCE | Force delete/purge object versions. |
| GLOBAL_PURGE | Purge object versions/whole objects outside workarea context. Empty the global wastebasket/all wastebaskets. Note: the global context wastebasket is a repository-wide wastebasket that is not associated with any particular workarea. |
|
Repository privilege |
Allows a user to... |
|---|---|
| CONNECT_VIA_RON | Connect to the repository via the Repository Object Navigator. |
| CONNECT_VIA_MATRIX | Connect to the repository via the Matrix Diagrammer. |
| CONNECT_VIA_REPORTS | Connect to the repository via the Reporting Tool. |
| CONNECT_VIA_CLI | Connect to the repository via the Command Line Tool. |
| CONNECT_VIA_VHV | Connect to the repository via Version History Viewer. |
| CONNECT_VIA_VEV | Connect to the repository via Version Event Viewer. |
Some commands and command options work only with a repository that supports versioning (a versioned repository). If you issue a command that requires a versioned repository for a repository that does not support versioning, an error is generated.
The command specifications specify which commands and options need a versioned repository.
To enter a command you enter the command name, the arguments and the options.
The first item in a command is the command name. Some commands have one or more aliases or short names, which can be used instead of the command name; all these are shown in the command specifications in brackets after the command name, for example:
checkin (ci)
where checkin is the command name and ci is an alias that can be used instead.
Commands and their aliases (short names) can be entered in upper case or lower case.
The list of arguments can be specified either before or after the list of options, but all the arguments must be together, either all before the options or all after the options. For example, any of the following could be used, where download is the command name, fol1\*.txt and c:\fol1 are both arguments and -s and -ow are both options:
download fol1\*.txt c:\fol1 -s -ow
download fol1\*.txt c:\fol1 -ow -s
download -s -ow fol1\*.txt c:\fol1
download -ow -s fol1\*.txt c:\fol1
In general, arguments identify the objects on which the command is to operate. Arguments must be separated from each other by at least one space.
The order of arguments is important: arguments for each command must be specified in the correct order as shown in the command's command specification.
For details of how to identify objects in arguments, see Identifying objects.
For details of the case sensitivity when identifying objects, see Case sensitivity for identifying objects.
In general, options specify how the command is to operate. An option is a string prefixed by a hyphen ( - ).
Option names are not case-sensitive.
Some options need a corresponding option value and others do not. The option values for some options are optional.
Where an option value is needed, it can be separated from the option by an equals sign ( = ) or not separated at all. For example, either of the following could be used where the option is -br followed by a branch name mybranch:
checkin -br=mybranch myfile
ci -brmybranch myfile
Options can be specified in any order and do not have to be separated by space, for example:
lsfolder -rp-o-c-u-lk-ir-iv-vl
Arguments or option values that contain spaces must be enclosed in double quotation marks, for example:
set workarea "my workarea"
checkin -nt"A new set of notes." "my file.txt"
Many commands allow the use of wildcard characters in strings, to find items whose names match a certain pattern. Details of where wildcards can be used are given in the individual command specifications.
Wildcard characters are:
* matches a substring
? matches any single character
Some commands allow filtering of the objects on which they operate. For example, some commands have a -ty<element-type> option that allows you to specify what type of objects are to be used by the command. The -ty<element-type> option is useful particularly where there might be objects with the same name but of different types.
For example, to check in all the objects of type Entity that have names matching the pattern CUST*, but not check in any other objects with matching names, a command such as the following could be used:
checkin CUST* -tyEntity
For some commands, when you are operating on a configuration, you need to use the -ty option to indicate that the object is a configuration. See Identifying configurations.
You can find out the element type of objects using the lsfolder command and specifying the -ty option, for example:
lsfolder -ty
Details of any such filtering and listing options are included in the specifications of individual commands.
The following examples show the different ordering of options and arguments and the different ways of presenting options. All of the following perform the same operation; only the checkout notes are different:
checkout -lk -ntNotes my_file.txt
checkout my_file.txt -lk -nt=Notes
co -lk -nt"New Notes" my_file.txt
checkout -lk -nt="New Notes" my_file.txt
co -lk-ntNotes my_file.txt
To start the Command Line Tool on Windows systems from the Repository Object Navigator:
If a workarea is currently selected, the Command Line Tool opens with this workarea as the context workarea. If no workarea is selected, use the set workarea command to set the workarea context.
The Command Line Tool session uses the current connection established for the Repository Object Navigator.
Note, the Command Line Tool can also be started on Windows systems from the Start menu.
To start the Command Line Tool from the operating system command line, use the repcmd command. The simplest way to start the Command Line Tool in interactive mode is to issue the repcmd command with no arguments. This command starts a Command Line Tool session.
Within the session you can issue a connect command to connect to a repository and a set workarea command to establish a workarea context for the session. To connect to a repository via the Command Line Tool, you must have the CONNECT_VIA_CLI repository privilege.
A sequence of interactions could be as follows, where the strong characters indicate output on the display:
>repcmd
repcmd>connect JRMAP/asdfghj@dev
repcmd>set workarea devworkarea
repcmd>devworkarea\>>
The general form of the command to start an interactive session from the operating system command line is:
repcmd [-c<connect-string>] [-w<workarea-name>] [-da_classpath<class-path>]
The general form of the command to start the Command Line Tool in one-shot mode is the same as for an interactive session except that the command to be executed is also given:
repcmd [-c<connect-string>] [-w<workarea-name>] [-da_classpath<class-path>] <command>
In both the above formats:
<connect-string> has the form:
<username>/<password>@<database-alias>
<workarea-name> specifies the name of a workarea.
-da_classpath"c:\source1;d:\another folder"
-da_classpath"%JVM_CLASSPATH_Repository Object Navigator%"
When the environment variable is passed into the tool, it is expanded to the full string value, so if there are any spaces in the <class-path> string, it must be enclosed in quotation marks.
For more information about the -da_classpath option, see The Dependency analyze class path option
When you enter a repcmd command, values that contain one or more spaces must be contained in quotation marks.
Examples of starting an interactive session:
repcmd
repcmd -cjbh/abcd1234@connStr
Examples of running one-shot mode:
repcmd help
repcmd -cjbh/abcd1234@connStr -wMyWorkArea upload c:\fol1\*.txt fol1 -s -vp
When you start the Command Line Tool in interactive mode, you enter a command shell session where you can type commands and have them executed. The session lasts as long as you remain in the shell. You can set up various session variables that apply until the session ends (see set command).
Once a Command Line Tool interactive session is started, you can connect to a repository. You can change the connection at any time during the session using the connect command. You can disconnect from the repository using the disconnect command.
Operating system environment variables are not available to Command Line Tool commands executed in interactive mode.
For an interactive session of the Command Line Tool, there are two separate contexts, one in the context workarea in the repository and one in the file system.
Some commands can work in either the repository context or the file system context, for example, lsfolder, which lists container contents, and lsworkingfolder, which displays details of the current working folder. By default, these commands work within the repository structure. Each of these commands has options that you use to specify whether the repository context or the file system context is to be used:
To display the path of the current context containers, use the lsfolder command; for the repository context use the -rp option; for the file system context, use the -lo option.
To set the current context folder use the changefolder command; for the repository context folder use the -rp option; for the file system context folder use the -lo option.
Generally, the repository is the master context, unless a particular command specifies otherwise. Any mappings between the file system and the repository are resolved transparently.
Some commands operate only in the file system context (for example, the upload command). Some commands can work in either the repository or the file system context. If you are working in the file system context only, you do not need a connection and a workarea to be set.
Interactions with the repository via the Command Line Tool are in the context of a current workarea.
If you start the Command Line Tool from the Repository Object Navigator with a workarea selected, or if you supply a -w<workarea> in the command to start the Command Line Tool, that workarea is initially the context workarea for the session.
To set, change or unset the current workarea from within a Command Line Tool session, use the set workarea command.
The command prompt in an interactive session displays the current workarea and current repository context container.
To display current context, use the lsworkingfolder command. To display the repository context, use the -rp option. To display the file system context, use the -lo option.
To display all the session variables and their current settings and other information about the session, use the show command.
Some commands produce output that needs a display space wider than the command screen or window, and some commands produce output that is longer than the command screen or window. To handle such output, the screen buffer must be set to enable horizontal and vertical scrolling. For instructions on how to do this, consult the documentation for the operating system or windowing system.
For environments where scrolling cannot be enabled (such as DOS sessions in Windows 95 and Windows 98), the following options are available for viewing long output:
By default, commands other than vhv and vev do not provide any interaction with the user in the form of prompts, and avoid using graphical interfaces available with certain commands such as compare. This is because typically, the Command Line Tool is used to run batch scripts containing high volumes of individual operations, and prompting or using graphical interfaces would halt batch operations while any command that offers them is being executed.
When you use the vhv and vev commands, the graphical user interface is always displayed. The commands compare and merge also run tools that have graphical user interfaces. For all these commands, once the graphical user interface for the appropriate tool is displayed, you can continue to work within this displayed interface, performing further actions within the tool. For example, if you use the vhv command to look at the version history for an object, you can compare versions of the object using the Version History Viewer display several times if necessary. When you exit from the graphical tool, control returns to the Command Line Tool.
Other commands use prompting for various reasons. For example, the checkin command can use prompting to prompt the user to enter details of the checkin. You can set the command line tool to use prompting for all commands that support it, or can specify in individual commands that prompting is to be used.
To use prompting and graphical user interfaces for all commands that provide them, use the set prompting command to set the session level variable PROMPTING to on.
set prompting on
To switch prompting off for the session, use:
set prompting off
For example:
set prompting on
...
rmfolder myfolder
...
checkin *.ext
...
set prompting off
To use prompting or a graphical interface for an individual command that has such a feature, use the -p option. For example, the following command prompts the user to confirm that the folder is to be removed:
rmfolder myfolder -p
The following command prompts the user for checkin details:
checkin *.ext -p
The effects of prompting for each command are described in the command specifications.
To run an operating system command or application, use the exec command, specifying the name of the command or application in the usual way for the operating system. If the application is not on the path, a fully qualified path name must be given for it, either an absolute path or a path relative to the context file system folder.
Any application started in this way runs as a discrete process separate from the interactive session.
In interactive mode, interactions with the Command Line Tool can be captured in a file as well as being displayed on the screen. A set spool command is used.
To start spooling to a file, use a set spool command to specify a file to be used as the spool file for the session:
set spool <spool-filename>
To stop spooling to the spool file, use:
set spool off
To start spooling again, appending the new interactions to the end of the spool file, use:
set spool on
Some commands, such as lscheckout, checkout, and checkin, allow output to be redirected to a specified file or input to be read from a specified file. This information is given for each such command in the command specifications under the File redirection heading. For example, the checkout command and the lscheckout commands can write to a file a list of the IRID/IVID pairs of the objects checked out. The same file can be used as input to the checkin command to check the same objects in again. For example:
lscheckout > co_files.txt
checkin < co_files.txt
The lsworkarea command can output a workarea specification to a file. This file can then be used, either as is or edited, in a mkworkarea command to be the specification of a new workarea. For example:
lsworkarea fix06_pjh > c:\fixworkspec.txt
mkworkarea myworkarea -fs"c:\fixworkspec.txt" -brfix06
To end a Command Line Tool interactive session, use the exit command. When you exit, the Command Line Tool commits outstanding transactions. For details of committing transactions, see Commit cycle, savepoints and rollback
To end a long-running command in an interactive session, close the session or use xterm.
In one-shot mode, the repcmd command executes a single Command Line Tool command and exits. Not all commands can be run in one-shot mode. For details of a particular command, see the command specification for that command.
By default, commands do not provide any interaction with the user in the form of prompts, and avoid use of graphical interfaces available with certain commands such as compare. This is because, typically the Command Line Tool is used to run batch scripts containing large numbers of individual operations, and prompting or use of graphical interfaces would halt processing of later commands until input is provided.
However, prompting for interaction with the user and graphical interfaces are available for some commands and can be invoked using the -p option where it is provided, for example:
rmfolder myfolder -p
checkin *.ext -p
The effects of prompting for each command are described in the command specifications.
In one-shot mode, output can be redirected to a file using the file redirection facilities provided by the operating system. For example:
repcmd -cjbh/abcd1234@connStr lsworkarea > c:\lists\workarea_list.txt
To end a long-running command that has been started in one-shot mode, you must end the entire process using the operating system facilities.
There are two ways of executing a series of commands using the Command Line Tool: using an operating system script and using the @ command
By default, commands do not use prompting and do not use the graphical interfaces available with some commands such as compare.
Using both methods of running several commands, care must be taken over the use of prompting: if prompting is used, any command that needs input will halt processing of later commands until input is provided. For this reason, prompting is not the default, and must be specified explicitly.
A series of calls to repcmd can be included in an operating system script and executed from the command line as a batch.
Each command in the script file is a repcmd command that executes a single Command Line Tool command in one-shot mode. Using one-shot mode, operating system batch files and scripts can access repository functionality. It acts like any other operating system command, so environment variable expansion, operating system pipes and scripting are all available.
The Command Line Tool @ command can be used to execute a series of Command Line Tool commands held in a file. The @ command can be issued either from within an interactive session or in one-shot mode.
Comments can be included in the file. Comment indicators are:
By default, when commands are being executed, execution continues when an error occurs. To halt execution when an error occurs, set the session variable ON_ERROR, using a set on_error command. Using this session variable you can specify whether, when an error occurs in executing a command, execution is to stop or continue.
To pause execution of a script at a certain point, use the pause command at that point. To restart processing when it has been paused, press Enter.
For example, the following could be used from the command line to execute all the commands in file update.rcl:
repcmd @update.rcl
The file update.rcl could contain commands such as:
connect MyConnect
set workarea MyWorkarea
changefolder -rp specifications
lscheckout *.html -nt"to update for task 568" >all_co.txt
...
checkin -iv < all_co.txt
exit
In the @ command, you identify the file that contains the commands to be executed. @ commands can be included in the file of commands, and in this way series of commands can be nested.
Generally, arguments to commands identify objects. Objects can be identified in the following ways, and the command specifications indicate which are valid for each argument:
Many of the commands can be performed in the context of a repository folder or file system folder, in which case only relative paths need to be specified.
A version-resolved name identifies an object version by specifying the name of the object and the version. Details of how to specify version-resolved names are in the following sections.
An object visible in a context workarea is already version resolved, because only one version of an object is visible in the workarea, and the object so can be identified simply by name, without a version label or branch label, as follows:
[<folder-name>/]*<object-name>
where the * indicates that the previous optional group can be repeated a number of times.
Example:
folder1/folder2/bigfile.txt
Using version-resolved names, you can identify objects that are not visible within the current context workarea. This feature is used by commands such as compare, merge, and checkout.
Although you can identify object versions that are not visible in the workarea, you cannot navigate to them. For example, the changefolder command cannot be used to set as the context folder a folder that is outside the context workarea.
The format for specifying a version-resolved name is:
<object-name>{<branch-label>;<version-sequence>}
where:
Examples:
ENTITY{MY_BRANCH;3}
report.txt{MAIN;LATEST}
If an object has a version label, the following form can be used instead of the branch and version sequence:
<object-name>{<version-label>}
Example:
mydoc{1.0}
The names used for the objects identified by arguments must match those stored in the repository: they may be treated case-sensitively or not, depending on the setting of the MATCH_CASE session variable.
If this session variable is switched on, which it is by default, when you are searching for or identifying objects, only objects whose names match the same pattern of upper and lower case as the text you specified are found. If you switch this session variable off, any objects whose names match the specified characters irrespective of case are found. Typically, you might switch the MATCH_CASE session variable off when you are searching for objects and are unsure about the capitalization of the names, or when you are running scripts and cannot be certain of the capitalization used for the names of objects by the operating system.
To switch the value of the session variable MATCH_CASE, use the set command.
To identify an object version in a container hierarchy, the version-resolved name must include the versions of the containers separated by slash characters. If a leading slash character is given, the name specified is an absolute path, otherwise it is considered to be relative to the context repository folder (see File navigation).
Objects in the path are identified using the forms shown in the section Format for identifying objects.
The general forms of specifying version-resolved names are:
[<folder-name>{<branch-label>;<version-sequence>}/]*<object-name>{<branch-label>;<version-sequence>}
[<folder-name>{<version-label>}/]*<object-name>{<version-label>}
where:
The following are examples of the format using <branch-label>;<version-sequence>:
folder1{MAIN;LATEST}/folder2{MAIN;LATEST}/bigfile.txt{MAIN;LATEST}
folder1{MY_BRANCH;1}/folder2{MY_BRANCH;1}/bigfile.txt{MY_BRANCH;3}
folder1{MAIN;LATEST}/myfile{labelABC}
The following is an example of the format using <version-label>:
folder1{LABEL1.0}/folder2{LABEL1.0}/bigfile.txt{LABEL3.0}
Patterns can be used in the name part of a path. Patterns cannot be used for the <branch-label>, <version-sequence>, or <version-label> part of a path. The wildcard characters are:
* matches any string
? matches a single character
Examples:
fol1{MAIN;LATEST}/fol2{MAIN;LATEST}/?igfile*{MAIN;5}
fol1{LABEL1.0}/fol2{LABEL1.0}/bigfile*{LABEL3.0}
The names of folders, workareas and configurations you create with the Command Line Tool can contain special characters such as { } (braces) and ( ) (parentheses), and other repository objects may also have names that include special characters. The special characters are characters that have some special meaning in a version-resolved name.
Any Command Line Tool commands that are searching for names matching a particular pattern find all such names, incluing those containing special characters. For example, the following command would find the object with name TEST_DATA(3)along with all other objects whose names start with TEST:
checkin TEST* -tyFile
Therefore, if a name contains one of these characters, it must be labeled so that the character is treated as part of the name itself, rather than with its special meaning.
However, if you use a Command Line Tool to search for a single object with a name that includes a special character, the special characters need to be signaled with an escape character, to indicate that the character forms part of the name. The escape character is ^ (caret).
The special characters that must be signaled in this way are:
/ (slash) \ (backslash) ^ (caret) . (period) ; (semicolon) { } (braces) ( ) (parentheses) = (equal sign) * (asterisk) ? (question mark)
Example:
To address an object called MyEntity(new/12) held in a folder called Entities;{local}, the escape character ^ is needed before each of the characters ; ( ) { } and / as follows:
Entities^;^{local^}/MyEntity^(new^/12^)
In addition to names and version labels, objects and object versions can be identified in some Command Line Tool using numbers that uniquely identify and object or an object version.
A repository object identifier, or IRID, is a 38-digit numeric code that uniquely identifies an element.
A repository object version identifier, or IVID, is a 38-digit numeric code that uniquely identifies an object version, that is, a particular version of an object, even if the object has not been brought under version control. If the object is not versionable (for example, a workarea) its IVID is 0.
In the Command Line Tool, some commands allow objects to be identified using IVIDs or IRID/IVID pairs. For example, the checkout command can write to a file IRID/IVID pairs for all the objects that are checked out by the command. The same file can then be used to check the same files in again using the checkin command.
Note: IRIDs and IVIDs are internal identifiers and where possible, for future compatiblity, users should use other methods of identifying objects.
Configurations are not held in containers, so they cannot be addressed relative to any folder context; instead, they must be addressed using absolute paths.
For some commands, such as checkout, you need to identify the version of the configuration to be checked out, for example:
checkout fix06-config{1.1}
For some commands, such as checkin, when you are operating on a configuration, you need to use the -ty option to indicate that the object is a configuration, for example:
checkin fix06-config -ty=Configuration
Details of such features are included in the command specifications.
The Command Line Tool accepts either / (slash) or \ (backslash) characters in paths.
Any path that has a leading / (slash) or \ (backslash) character is treated as an absolute path: the initial / or \ character refers to the root folder in the file system or the topmost level in the repository hierarchy. A path without a leading / or \ character is taken to be relative within the current context folder.
Case sensitivity uniqueness for filenames is governed by the CASE_SENSITIVE_FILENAMES policy set up for the repository.
To check the current setting of the case-sensitive uniqueness checking policy, use the lspolicy command.
To set the policy, use the setpolicy command.
Command history is provided via the DOSKEY program.
The Command Line Tool run in interactive mode operates in the context of a session. A number of session variables are used by the tool to store values and settings that apply for the session or for the current workarea context.
To see a list of the session variables and their settings, use the show command.
For details of the session variables and their scopes, see Session variables.
The repository context folder and the file system context folder remain throughout the session, unless explicitly changed using a changefolder command with the -rp option for the repository context or the -lo option for the file system context.
Session variables that relate to the workarea are reset when you change the workarea using a set workarea command. The workarea session variables are:
Other session variables stay in force for the session or until you change them explicitly using a set command.
The Command Line Tool provides a number of list commands to list, for example, folders and their contents, configurations, branch labels, or checked-out objects. The output from the list commands is in some cases formatted using headings and indentation to make the output easy to read.
However, you may want to use the output from some of the list commands in other Command Line Tool commands or in operating system commands. For this reason, a feature is provided for switching off the formatting and headings in such output.
Changes you make to a repository using the Command Line Tool are not necessarily committed to the repository immediately. This section describes the features available for committing and rolling back changes make using the Command Line Tool.
In one-shot mode, the Command Line Tool performs commits after each command that requires changes to the repository.
In interactive mode, changes you make to the repository using the Command Line Tool are not committed when they are made. All updates and insertions made since either the beginning of the session or since a previous commit command was issued are committed when you carry out any of the following:
However, you can specify that changes are to be committed automatically after a specified number of changes have been made. The COMMIT_FREQUENCY session variable is used to record the number of changes to be made before they are automatically committed. For example, if the COMMIT_FREQUENCY is set to 10, changes are committed when there are 10 changes waiting to be committed.
The COMMIT_FREQUENCY value is used by commands that perform multiple operations, such as checkin. If no COMMIT_FREQUENCY value has been set, none of the checkins performed by the checkin command are committed until the command has finished and a commit command is issued. However, if a COMMIT_FREQUENCY value has been set, the checkins carried out by the checkin command are committed according to that COMMIT_FREQUENCY value.
To set a value in the COMMIT_FREQUENCY session variable, use the set command.
To switch off the automatic commit, set the COMMIT_FREQUENCY session variable to 0.
In a Command Line Tool interactive session, any changes that have not been committed can be rolled back.
You can roll back either all changes since the last commit or all changes since a previous savepoint.
To roll back all changes made since the previous commit or since the beginning of the session, use the rollback command with no argument.
To set up a savepoint, use the savepoint command at the point to which you might later want to roll back changes. You give each savepoint a name.
To roll back updates made since a particular savepoint was set up, use the rollback command specifying the savepoint to which changes are to be rolled back. The updates are rolled back, and the savepoint is retained so that it can be used again.
For commands that have an -nt[<notes-string>] option, the value to be used for the notes string is determined as follows:
For commands that have a -br[<branch-name>] option, the value to be used for the branch name is determined as follows:
For the dependencyanalyze command class path option -cpth[<class-path>], the value to be used for the class path is determined as follows:
Two mechanisms are available for capturing the output from a command in a file and using a file as input to a command:
The lscheckout command can write a list of the IRID/IVIDs pairs of checked-out objects to a file. To do this, include a > character, which is the redirection character for output, and a <filename> at the end of the command.
The checkin can take as input a redirected file of IRIDs for the objects to be checked in, by including a < character, which is the redirection character for input, and a <filename> at the end of the command.
For example:
checkout *.htm* > co_objects.txt
...
checkin -iv < co_objects.txt
Chaining of commands is not supported, which means that you cannot take the output from a command to use directly as the input for another command in the same step. For example, the following command would not work:
lsco * > ci
The command specifications indicate whether input or output redirection is provided for individual commands.
Some commands have options that allow output to be written to or read from files.
The lsworkarea command can write the specification of one workarea to a specified file. The -fs<filename> option is used.
The mkworkarea command, the mkconfig command and the updconfig command all allow input defining the new or updated specification to be taken from some specification rules held in a file. The -fs<filename> option is used.
The command specifications for individual commands that have an -fs option explain how that option can be used.
For details of the formats for rules contained in a workarea specification or a configuration specification, see Workarea and configuration specification repository rules.
The Command Line Tool displays the repository as a hierarchical directory listing where container objects appear in square brackets (denoting that there may be subdirectories) whilst other objects appear without brackets. Only version-resolved names are shown, because repository listings can be shown only in the context of a workarea.
For commands that need to address the local file system an -lo option is provided.
Both the repository structure and the file system structure can be navigated using relative names or absolute names.
Relative names (names relative to the current folder) can be used with all commands that accept object names or file names in the current context, for example, checkin and checkout. For example, if the following command is issued when the repository context is \fol1\fol2, it would check in the file \fol1\fol2\myFile.txt:
checkin myFile.txt -nt"some notes"
In the same way, if the repository context is \fol\fol2, the following command would check in file \fol1\fol2\fol3\myFile.txt:
checkin fol3\myFile.txt
Absolute names can be expressed as follows:
For example, to change the repository context to fol2, commands of the following forms could be used:
For the repository context: changefolder -rp \fol1\fol2
For a Windows NT file system: changefolder -lo c:\tmp
The following navigation features can be used:
changefolder -lo ../../..
You can perform a file mapping operation to associate a container in the repository with a directory in the file system.
To create a mapping between the file system and the repository, use the mkfoldermap command.
For details of commands to use for uploading and downloading between the file system and the repository, see Uploading and downloading. For details of commands for synchronizing the file system and the repository, see Synchronizing the file system and the repository.
The upload and download commands copy files and directories between the file system and the repository. These operations do not need a container mapping; instead, the file system path and repository path are specified with the command. For example, the command:
upload c:\folder1\* \fol1
makes a copy of the contents of the file system directory c:\folder1 in the repository folder \fol1.
These operations do not create new versions of the objects copied.
When a file is uploaded to the repository, or when a container is created to contain files uploaded to the repository, the name of the file or folder as known to the operating system (not its displayed name) is stored in the Name property of the corresponding object in the repository. When the file is downloaded, the name stored in the Name property of the object in the repository is used to name the object in the operating system. That is, the repository does not transform filenames in any way during download or upload.
If you are uploading large numbers of files and folders, you may need to increase the Java heap size to avoid running out of memory. This might apply when you are running any of the following commands:
checkin
checkout
dependencyanalyze
import
synchronize
upload
To increase the Java heap size on Windows systems you should increase the following values in the registry:
HKEY_LOCAL_MACHINE\SOFTWARE\ORACLE\repadm61\CKDM_JVM_PARAMS\JVM_MAX_HEAP_SIZE
HKEY_LOCAL_MACHINE\SOFTWARE\ORACLE\repadm61\CKTL_JVM_PARAMS\JVM_MAX_HEAP_SIZE
The synchronize command explicitly synchronizes the repository and the file system for specified objects.
Using the commands checkin and checkout, you can specify whether or not the file system and the repository are to be synchronized before the commands are carried out and, if they are to be synchronized, how new files in the file system are to be handled.
To synchronize the file system and the repository, there must be a mapping between a root container in the repository and a directory on the file system. A root container is any container that does not have an owning parent. Any root container can be mapped to a directory on the file system using the mkfoldermap command.
Once there is a mapping, checkin and checkout operations can be performed on any object under the root container. Any changes can be reflected between the operating system and repository and vice versa using the synchronization commands so that the two keep in step.
For large uploads from the file system, you may need to increase the Java heap size. For details, see Uploading and downloading
Filenames in Windows and DOS file systems are treated by the operating system as case-insensitive, so that the three filenames above are all equivalent. Windows graphical user interface tools such as the Explorer may display filenames in some particular display format, but the underlying operating system treats all upper and lower case variations of the same name as one filename.
The repository implements its own uniqueness checking of filenames. By default, the repository treats filenames in a case-sensitive way. A user with SET_POLICY repository privilege can switch between case sensitivity and case insensitivity (Windows).
Before you switch on uniqueness checking, if there are any duplicate names, resolve them manually by renaming files.
Setting the CASE_SENSITIVE_FILENAMES policy to case insensitivity switches on uniqueness checking for filenames: the repository will not allow multiple names that are the same but of different case to be stored in the repository.
To set the repository case-sensitivity filenames policy from the Repository Object Navigator:
To set the repository case sensitivity policy from the Command Line Tool:
Note that disabling uniqueness checking may result in some performance overhead, because the repository indexes can no longer be used as the sole constraint.
Workareas and configurations are defined by specifications, which can be held in specification files. Specifications consist of sets of rules that define which object versions should be included in the workarea or configuration and which should be excluded. By convention, the file extension for specification files is .cws.
The rules in a specification file are applied in order, starting with the first rule in the specification, so that, for example, the first rule could include a whole range of objects, perhaps using an INCLUDE_FOLDER rule, and a subsequent rule could exclude specific objects using an EXCLUDE_OBJECT rule.
When you are creating a workarea or a configuration using the Command Line Tool, you can either supply a set of rules in a file or supply a single rule in the mkworkarea or mkconfig command. In a similar way, when you update a workarea or a configuration, you specify any changes to the specification using rules.
If the rules are in a file, the file is easier to read if each rule is on a separate line.
The general forms of repository rules are:
<RULE_NAME>(<object>[=<element-type>][,<parameters>])
<RULE_NAME>(<branch-label>[,<parameters>])
For example:
INCLUDE_FOLDER(reports{1.2.1.1})
EXCLUDE_OBJECT(reports{1.2.1.1}/LIST OF THINGS{1.1}=Domain)
FOLDER_LATEST_CONTENTS(reports{1.2.1.1},fix06)
LATEST_BETWEEN(fix06,24-FEB-2000,19-APR-2000)
To see a list of available rules and the formats for defining them, use the lsrules command. You can spool the output from this command to a file and then use that file as a template for creating new rules. Alternatively, you can output an existing workarea specification to a file using the lsworkarea command and use that as a template for creating new rules.
Objects are identified in rules using version-resolved names. The type of object can be specified in addition to the version-resolved name by including an equal sign and the element type or the short name of the object after the name.
You can find out the element type of objects using the lsfolder command and specifying the -ty option, for example:
lsfolder -ty
If any special characters are used in an object name, they must be preceded by a caret mark, as described in Special characters in version-resolved names.
Object versions are identified using the forms described in Format for identifying objects.
Some repository rules require dates to be included. Dates can be given in either of the following formats:
You can also use the default format for the database.
The available rules are as follows:
The EXCLUDE_FOLDER repository rule excludes all specified container versions and their contents.
EXCLUDE_FOLDER(<folder-path>)
where each entry in the <folder-path> can have the form <name(spec)>[=<element-type>]
Examples:
The following excludes version 1.2.1.1 of folder reports
EXCLUDE_FOLDER(reports{1.2.1.1})
The following excludes the version of folder fix(reports) that is on branch fix06 and has sequence number 4 on that branch:
EXCLUDE_FOLDER(fix^(reports^){fix06;4}=Folder)
The EXCLUDE_OBJECT repository rule excludes all the specified object versions.
EXCLUDE_OBJECT(<object-path>)
where each entry in the <object-path> can have the form <name(spec)>[=<element-type>]
Examples:
The following excludes version 1.1 of the domain LIST OF THINGS in version 1.2.1.1 of folder reports:
EXCLUDE_OBJECT(reports{1.2.1.1}/LIST OF THINGS{1.1})
The following excludes the object MASTER TABLE that has the version sequence 6 on the MAIN branch that is in the latest version of the MAIN branch of folder reports:
EXCLUDE_OBJECT(reports{MAIN;LATEST}/MASTER TABLE{MAIN;6}=Table Definition)
The FOLDER_LATEST_BEFORE repository rule includes the latest versions of all objects in the specified containers that were checked in before the specified date, and all container versions in the path.
FOLDER_LATEST_BEFORE(<folder-path>,<before-date>)
where each entry in the <folder-path> can have the form <name(spec)>[=<element-type>]
Examples:
FOLDER_LATEST_BEFORE(wa-specs{1.0.1.0},19-APR-2000)
FOLDER_LATEST_BEFORE(reports{1.2.1.1}=Folder/fix06{1.2},19-APR-00 08:00:00)
The FOLDER_LATEST_BETWEEN repository rule includes the latest versions of all objects in the specified containers that were checked in between the specified dates, and all container versions in the path.
FOLDER_LATEST_BETWEEN(<folder-path>,<start-date>,<end-date>)
where each entry in the <folder-path> can have the form <name(spec)>[=<element-type>]
Example:
The following includes the only or the latest versions of all objects in folder wa-specs{1.0.1.0} between the given dates:
FOLDER_LATEST_BETWEEN(wa-specs{1.0.1.0},19-APR-2000,30-APR-2000)
The FOLDER_LATEST_CONTENTS repository rule includes the latest versions of all objects in the specified container on the specified branch, and all container versions in the path.
FOLDER_LATEST_CONTENTS(<folder-path>,<branch-label>)
where each entry in the <folder-path> can have the form <name(spec)>[=<element-type>]
Example:
The following includes the latest versions of objects in folder reports{1.2.1.1} on branch fix06:
FOLDER_LATEST_CONTENTS(reports{1.2.1.1},fix06)
INCLUDE_CONFIG, while not strictly a repository rule, has a similar format to repository rules. It is used to include a configuration, that is, to include all the object versions defined by a configuration.
INCLUDE_CONFIG(<configuration>)
Example:
The following includes all the object versions defined by the configuration version services_internal{1.0}.
INCLUDE_CONFIG(services_internal{1.0})
The INCLUDE_FOLDER repository rule includes the latest versions of all objects in the specified containers, and all container versions in the path.
INCLUDE_FOLDER(<folder-path>)
where each entry in the <folder-path> can have the form <folder-name>[=<element-type>]
Example:
The following includes the latest versions of all objects in the version of folder reports that has sequence number 5 on the MAIN branch:
INCLUDE_FOLDER(reports{MAIN;LATEST})
INCLUDE_FOLDER(reports{MAIN;5}=Folder)
The INCLUDE_OBJECT repository rule includes the latest or the specified version of the specified object, and all container versions in the path.
INCLUDE_OBJECT(<object-path>)
where each entry in the <object-path> can have the form <name(spec)>[=<element-type>]
Example:
INCLUDE_OBJECT(my_fol{1.0}/*.sql{MAIN;LATEST)
INCLUDE_OBJECT(reports{1.2.1.1}/LIST OF THINGS{1.0}=Domain)
The LATEST repository rule includes the latest versions of all objects on the specified branch.
LATEST(<branch-label>)
Example:
The following includes the latest versions of objects on branch fix06:
LATEST(fix06)
The LATEST_BEFORE repository rule includes the latest versions of all objects on the specified branch that were checked in before the specified date.
LATEST_BEFORE(<branch-label>,<before-date>)
Example:
LATEST_BEFORE(fix06,19-APR-2000)
The LATEST_BETWEEN repository rule includes the latest versions of all objects on the specified branch that were checked in between the specified dates.
LATEST_BETWEEN(<branch-label>,<start-date>,<end-date>)
Example:
LATEST_BETWEEN(FIX06,19-APR-2000,30-APR-2000)
The LATEST_CONFIG_CONTENTS repository rule includes the latest versions of all the objects defined by the specified configuration.
LATEST_CONFIG_CONTENTS(<configuration>[=<element-type>],<branch-label>)
Example:
The either of the following could be used to include the latest version on branch fix06 of all the objects defined by configuration version fix_config{MAIN;LATEST}:
LATEST_CONFIG_CONTENTS(fix_config{MAIN;LATEST},fix06)
LATEST_CONFIG_CONTENTS(fix_config{MAIN;LATEST}=Configuration,fix06)
The LATEST_DIAGRAM_CONTENTS repository rule includes the latest versions of all the objects on the specified branch that make up the specified diagram.
LATEST_DIAGRAM_CONTENTS(<diagram-path>,<branch-label>)
where each entry in the <diagram-path> can have the form <name(spec)>[=<element-type>]
Example:
LATEST_DIAGRAM_CONTENTS(ANALYSIS{1.1}/PURCH{mod1;4}=Diagram,mod1)
To ensure that text files contain the end-of-line characters appropriate for the operating system of the client (Windows), the Command Line Tool can perform text conversion of files that are downloaded. Text conversion occurs only on download; this ensures the integrity of file data stored in the repository.
Because text conversion modifies file contents, there is a risk for binary and UNICODE files that data may be corrupted. So, it is recommended that you do not use text conversion on either binary or UNICODE files. Text conversion cannot be carried out on files that are registered (in the file type registry) as binary.
When a mapping is defined between the repository and the file system, you can specify a default text conversion to be used for files that are downloaded to the file system from the repository for that mapping: the mkfoldermap command is used to create the mapping.
At the time files are downloaded to the file system from the repository, using a download command or other command such as checkin, checkout, and synchronize that performs download operations, you can specify the kind of text conversion to be carried out; the -utxt (UNIX-to-Windows) or -wtxt (Windows-to-UNIX) option for the appropriate command is used.
If a download operation is required and no text conversion option is specified, the default conversion defined for the mapping is used, if any. Otherwise, no text conversion takes place. Two files with the same textual content, but different end-of-line characters are considered to be the same.
Text conversion can have significant performance penalties for a download operation. If it is known that text format conversion is not needed, the text conversion options for the mapping and for individual download operations should be avoided in the interests of performance.
|
|
|
