Description - Mks.com

ÁÁÁ 

Á 

ÁÁ

MKS Source Integrity® Enterprise 2005 

CLI Reference Guide 

Copyright © 2001–2005 MKS Software Inc.; in Canada copyright owned by MKS Inc. All rights reserved. 

MKS makes no warranty of any kind with regard to this material, including, but not limited to the implied warranties of merchant ability, 

performance, or fitness for a particular purpose. MKS shall not be liable for errors contained herein, or for any direct, indirect, incidental, 

or consequential damages resulting from the use of this material. 

No part of this publication may be reproduced, transmitted, transcribed, stored in a retrieval system, or translated into any language in 

any form by any means, without written permission from MKS. 

MKS Source Integrity, MKS Integrity Manager, Implementer, NewVersion, MKS Toolkit, Sandbox, NuTCRACKER, MKS Integrity 

Solution, MKS Integrity Suite, AlertCentre, and MKS Federated Server are trademarks or registered trademarks of MKS Inc. All other 

trademarks or registered trademarks are the property of their respective holders. 

Contains Java software developed by Sun Microsystems, Inc. © Copyright Sun Microsystems, Inc. All Rights Reserved. Java and Javabased 

marks are trademarks or registered trademarks of Sun Microsystems, Inc. in the United States and other countries. 

Contains embedded database © Copyright PointBase Inc. All rights reserved. 

Portions of this product are based upon copyrighted materials of BEA Systems Inc. All rights reserved. 

Portions of this product are based upon copyrighted materials of Sitraka Inc. (formerly KL Group) or its suppliers. All rights reserved. 

IBM Bean Scripting Framework (BSF) is incorporated in this product and is provided by International Business Machines or one of its 

subsidiaries (IBM) and is copyrighted and licensed. MKS does not make or imply any representations or warranties on behalf of IBM. 

Contains NSPR (Netscape Portable Runtime) library for C API. The Source Code version of the Covered Code is available under the terms 

of the Mozilla Public License Version 1.1. 

Licensed under the Apache License, Version 2.0 (the “License”); you may not use this file except in compliance with the License. You may 

obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0. 

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an “AS IS” BASIS, 

WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language 

governing permissions and limitations under the License. 

Contains XML parsing library for C. Copyright © 1998–2003 Daniel Veillard. All Rights Reserved. Permission is hereby granted, free of 

charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software 

without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies 

of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above 

copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS 

PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE 

WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT 

SHALL THE DANIEL VEILLARD BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF 

CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR 

OTHER DEALINGS IN THE SOFTWARE. 

This product includes software developed by the OpenSSL Project for use in the OpenSSL Toolkit (http://www.openssl.org). 

Copyright © 1998–2003 The OpenSSL Project. All rights reserved. 

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions 

are met: 

1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer. 

2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the 

documentation and/or other materials provided with the distribution. 

3. All advertising materials mentioning features or use of this software must display the following acknowledgment: 

“This product includes software developed by the OpenSSL Project for use in the OpenSSL Toolkit (http://www.openssl.org/)” 

4. The names “OpenSSL Toolkit” and “OpenSSL Project” must not be used to endorse or promote products derived from this software 

without prior written permission. For written permission, please contact openssl-core@openssl.org. 

5. Products derived from this software may not be called “OpenSSL” nor may “OpenSSL” appear in their names without prior written 

permission of the OpenSSL Project. 

6. Redistributions of any form whatsoever must retain the following acknowledgment: 

“This product includes software developed by the OpenSSL Project for use in the OpenSSL Toolkit (http://www.openssl.org/)” 

THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT “AS IS” AND ANY EXPRESSED OR IMPLIED WARRANTIES, 

INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 

PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR ITS CONTRIBUTORS BE LIABLE FOR ANY 

DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED 

TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 

HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 

(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED 

OF THE POSSIBILITY OF SUCH DAMAGE.

This product includes cryptographic software written by Eric Young (eay@cryptsoft.com). 

Copyright © 1995–1998 Eric Young (eay@cryptsoft.com). All rights reserved. 

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions 

are met: 

1. Redistributions of source code must retain the copyright notice, this list of conditions and the following disclaimer. 

2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the 

documentation and/or other materials provided with the distribution. 

3. All advertising materials mentioning features or use of this software must display the following acknowledgement: 

“This product includes cryptographic software written by Eric Young (eay@cryptsoft.com)” 

The word ‘cryptographic’ can be left out if the routines from the library being used are not cryptographic related. 

4. If you include any Windows specific code (or a derivative thereof) from the apps directory (application code) you must include an 

acknowledgement: “This product includes software written by Tim Hudson (tjh@cryptsoft.com)” 

THIS SOFTWARE IS PROVIDED BY ERIC YOUNG “AS IS” AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT 

LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE 

DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, 

SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 

SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND 

ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR 

OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH 

DAMAGE.

Corporate Headquarters Worldwide Offices: 

410 Albert Street 

Waterloo, ON N2L 3V3 

Canada 

tel: 519 884 2251 

fax: 519 884 8861 

sales (toll free): 800 265 2797 

www.mks.com 

This document is uncontrolled when printed or copied. 

1815 South Meyers Rd. 

Suite 220 

Oakbrook Terrace, IL USA 

60181 

tel: 630 827 4900 

fax: 630 629 9167 


12450 Fair Lakes Circle 

Suite 400 

Fairfax, VA USA 

22033 

tel: 519 884 2251 

fax: 703 803 3344 


Martinstraße 42-44 

73728 Esslingen 

Germany 

tel: +49 711 351775 0 

fax: +49 711 351775 7555 

Third Floor, Duke’s Court 

Duke Street, Woking 

Surrey 

GU21 5BH 

United Kingdom 

tel: +44 (0)1483 733900 

fax: +44 (0)1483 733901 

sales: +44 (0)1483 733919

MKS Source Integrity Enterprise (also referred to as simply Source Integrity) provides a complete 

command line interface (CLI) to manage Source Integrity projects and archives. The CLI and 

graphical user interfaces (GUI) provide the exact same functionality. In fact, in most cases, these 

two interfaces are interchangeable -- you can easily alternate between these interfaces and they 

are quickly synchronized to facilitate your user experience. 

Source Integrity commands follow the si prefix. For example, si about displays the product 

information for Source Integrity, while si co -l samplefile.c checks out a locked copy of a 

sandbox member file. 

Each command allows a limited set of options. Single letter options must always be preceded by a 

single dash ( - ), while longer option strings must be preceded by a double dash ( -- ). The long 

strings are not case sensitive, but are shown in mixed case to facilitate readability. 

To see a list of the available Source Integrity commands and brief descriptions of each, type si. 

To see a list of options available to a particular command, simply append -? or --usage to the 

command, for example, 

si add --usage 

In options, square brackets indicate optional strings, for example, the no is an optional prefix in -- 

[no]batch. The two ways to use this option would be --nobatch or --batch. 

For information on Authorization Administrator commands and permissions, see the MKS Integrity 

Server Administration CLI Reference Guide. 

Introduction 

● intro 

● man 

Source Integrity Commands 

● si about 

● si acceptcp 

1 of 457

● si add 

● si addlabel 

● si addmemberattr 

● si addmemberfromarchive 

● si addproject 

● si addprojectattr 

● si addprojectlabel 

● si addsandboxattr 

● si addsubproject 

● si annotate 

● si appendrevdesc 

● si applycp 

● si archiveinfo 

● si checkpoint 

● si ci 

● si closecp 

● si co 

● si configuresandbox 

● si configuresubproject 

● si connect 

● si cpissues 

● si createcp 

● si createdevpath 

● si createproject 

● si createsandbox 

● si createsubproject 

● si deletelabel 

● si deleteprojectlabel 

● si deleterevision 

● si demote 

● si demoteproject 

● si diff 

● si difffiles 

● si discardcp 

● si disconnect 

● si drop 

● si dropdevpath 

● si dropmemberattr 

● si dropproject 

● si dropprojectattr 

2 of 457

● si dropsandbox 

● si dropsandboxattr 

● si edit 

● si editcp 

● si exit 

● si freeze 

● si gui 

● si import 

● si importproject 

● si importsandbox 

● si integrations 

● si loadrc 

● si locate 

● si lock 

● si locks 

● si makewritable 

● si memberinfo 

● si merge 

● si mergebranch 

● si mods 

● si move 

● si movesubproject 

● si opencp 

● si print 

● si projectinfo 

● si projects 

● si promote 

● si promoteproject 

● si rejectcp 

● si rename 

● si report 

● si restoreproject 

● si resync 

● si resynccp 

● si revert 

● si revisioninfo 

● si rlog 

● si sandboxes 

● si sandboxinfo 

● si servers 

3 of 457

● si setmemberrule 

● si setprefs 

● si setprojectdescription 

● si sharesubproject 

● si snapshot 

● si submit 

● si submitcp 

● si thaw 

● si unlock 

● si unlockarchive 

● si updatearchive 

● si updateclient 

● si updaterevision 

● si viewcp 

● si viewcps 

● si viewhistory 

● si viewlabels 

● si viewlocks 

● si viewnonmembers 

● si viewprefs 

● si viewproject 

● si viewprojecthistory 

● si viewrevision 

● si viewsandbox 

Miscellaneous Information 

● ACL 

● cc 

● diagnostics 

● envvar 

● makefile 

● options 

● preferences 

● rcsedit 

MKS Toolkit Utilities 

Source Integrity provides the following MKS Toolkit command line utilities on the client: 

4 of 457

● ar 

● cc 

● cmp 

● cp 

● cxx 

● date 

● diff 

● diffb 

● diffh 

● echo 

● ident 

● less 

● ln 

● make 

● manstrip 

● more 

● mv 

● nm 

● rm 

● touch 

● vdiff32 

● whereis 

● which 

5 of 457

si intro 

introduction to reference pages 

DESCRIPTION 

A description of an individual topic (for example, a command) is loosely called the reference page 

for that topic, even if it is actually several pages long. 

There are three alternatives for accessing the reference pages to each MKS Source Integrity 

command through the CLI man command. 

First, you may simply type the si prefix and the command together as one word. Second, you may 

type the si prefix and the command with an underscore between them. Third, you may quote the 

si prefix and the command, with a space in the middle. For example: 

man siabout 

man si_about 

man "si about" (Windows client only) 

See the reference page for the man command itself, by typing man man, to find out more details. 

One new feature involves using the -h option which allows you to view the reference pages in 

HTML Help format (Windows client only). 

Note: 

To view Source Integrity online reference pages (CLI commands) in HTML Help, you must 

have Microsoft Internet Explorer 4.0 or higher installed. MKS recommends Microsoft Internet 

Explorer 5.0 to avoid any problems with HHCTRL.OCX. 

This reference page describes the parts of a reference page with examples taken from real MKS 

Source Integrity reference pages. 

The following sections discuss the various elements of a reference page. 

Name 

The NAME section provides the name of the command and a brief functional description. 

Synopsis 

In the reference page for a command, the SYNOPSIS section provides a quick summary of the 

6 of 457

command's format. For example, here is the synopsis of the si add command. 

si add [--archive=filename] [--author=name] [(--binaryFormat|--textFormat)] 

[(--cpid ID|--changePackageId=ID)] [--[no]defer] [--[no|confirm]closeCP] 

[--issueId=ID] [--description=desc] [--descriptionFile=file] [--issueId=ID] 

[(-l|--lock)] [--onExistingArchive=[confirm|sharearchive|newarchive|cancel]] 

[--[no]createSubprojects] [--[no]retainWorkingFile] [--[no]saveTimestamp] 

[--[no]unexpand] [(-r rev|--revision=rev)] [(-R |--[no|confirm]recurse)] 

[(-S sandbox|--sandbox=sandbox)] [--hostname=server] [--port=number] 

[--password=password] [--user=name] [--cwd=directory] [(-F file|--selectionFile=file)] 

[--forceConfirm=[yes|no]] [(-g|--gui)] [(-N|--no)] [--[no]batch] [--quiet] 

[--settingsUI=[gui|default]] [--status=[none|gui|default]] [(-?|--usage)] [(-Y|--yes)] 

nonmember... 

The synopsis takes the form of a command line as you might type it into the system; it shows what 

you can type in and the order in which you should do it. The parts that are enclosed in square 

brackets are optional; you may omit them if you choose. Parts that are not enclosed in square 

brackets must be present for the command to be correct. 

The synopsis begins with the name of the command itself. The Source Integrity commands all 

include the si prefix. In Source Integrity documentation, command names are always written in 

bold Courier font. 

After the command name comes a list of options. A typical Source Integrity command option 

consists of either a single dash (-) followed by a single character, usually an uppercase or 

lowercase letter, or it may consist of a double dash (--) followed by a multi-character option name. 

Often there are single-character and multi-character options that do the same thing. The multicharacter 

strings are not case sensitive, but are shown in mixed case to facilitate readability. For 

example, you might have -L or --label. 

The synopsis line shows options in bold Courier font. Note that the case of single-character 

options is important; for example, in the synopsis of si add, -r and -R are different options, with 

different effects. 

Furthermore, in the synopsis all options are shown in one long string. Other common option forms 

are: 

-r rev 

--revision=rev 

where rev or, in some cases, value provides extra information for using that option. For example, 

the si lock command locks sandbox members; here's the command's synopsis: 

7 of 457

si lock [--[no|confirm]branch] [(--cpid ID|--changePackageId=ID)] [--issueId=ID] 

[(-r rev|--revision=rev)] [(-R|--[no|confirm]recurse)] [--filter=filteroptions] 

[(-P project|--project=project)] [(-S sandbox|--sandbox=sandbox)] [--devpath=path] 

[--hostname=server] [--port=number] [--password=password] [--user=name] 

[(-?|--usage)] [(-F file|--selectionFile=file)] [(-N|--no)] [(-Y|--yes)] [--[no]batch] 

[--cwd=directory] [--forceConfirm=[yes|no]] [(-g|--gui)] [--quiet] 

[--settingsUI=[gui|default]] [--status=[none|gui|default]] member... 

In this example, there is the option 

-r rev 

This option tells the si lock command which revision to lock. In a command synopsis, anything 

appearing in italics is a placeholder for information that you are expected to supply. Sometime 

after the synopsis, the reference page explains what kind of information is expected in place of the 

placeholder. 

The end of the si lock synopsis is 

member... 

Since there are no square brackets around the list, in this example, it is mandatory. 

This means one or more member names; the ellipsis (...) stands for repetitions of whatever 

immediately precedes it. Most Source Integrity commands allow you to specify lists of multiple 

items using spaces between them. 

See the options reference page for more details on selecting members, sandboxes and projects. 

The order of items on the command line is important. When you type in a command line, you 

should specify the parts of the command line in the order they appear in the command synopsis. 

The exceptions to this are options marked with a - or a --; they do not have to be given in the 

exact order shown in the synopsis. However, all the - or -- options must appear in the correct 

area of the command line. For example, you can specify 

si lock -r 1.2 --gui member1 

si lock --gui -r 1.2 member1 

but you won't get correct results if you specify 

si lock member1 -r 1.2 --gui 

8 of 457

and so on. 

si lock -r 1.2 member1 --gui 

Description 

The DESCRIPTION section simply describes what the command does and how each option works. 

Inside the DESCRIPTION section, the names of files and directories are written in normal 

Courier font. The names of environment variables are written in italic Courier font. 

Diagnostics 

The DIAGNOSTICS division contains information about the exit status returned by the command. 

You can test this status to determine the result of the operation the command was asked to 

perform. 

See Also 

The SEE ALSO section refers to other reference pages that may contain information relevant to 

the reference page you have just read. 

9 of 457

NAME 

man — display online reference pages 

SYNOPSIS 

man [-wx] [-M path] [type] entry ... 

man [-wx] [-T txt_indexes] [type] entry ... 

man -h [-wx] [-C chm_indexes] [type] entry ... 

man -k [-M path] keyword ... 

DESCRIPTION 

man 

The man command either displays online reference pages or searches for reference pages that 

have specified keywords associated with them. 

Normally, man displays the reference page for each specified entry. To display only a reference 

page of a given type, specify type on the command line. type is a number representing which type 

of reference pages to search. Reference pages come in the following types: 

1 Commands and Utilities 

3 Functions 

4 File Formats 

5 Miscellaneous 

To indicate an operating system specific version of the entry (if one exists) or to indicate an 

command specific to a given set of commands and/or functions, append one of the following letters 

to the specified type: 

n for Windows NT/2000/XP/2003 

w for Windows Me 

t for Tcl 

When output is sent to the terminal, man invokes a pager command to filter and display the 

reference pages. If MANPAGER is defined, it is used. If not, and if PAGER is defined, it is used. If 

neither is defined, man defaults to using the command more -A -s. 

Options 

10 of 457

-C filelist 

specifies a list of .idx files (corresponding to .chm files) to search before searching the 

files listed in MAN_CHM_INDEX. 

-h 

-k 

launches the HTML Help viewer and displays the HTML Help version of the reference page. 

The reference page is found by searching each .idx listed in the MAN_CHM_INDEX file 

(or indicated by the -C option) for an entry matching entry and type that indicates which 

page in the corresponding .chm file to display. 

searches a precomputed database of synopsis lines for information on keywords. 

-M path 

searches the directories indicated by path for reference pages. If -M is not specified, man 

uses the path specified in the MANPATH environment variable if it is set; otherwise man 

searches ROOTDIR/etc. All reference pages are found by searching similarly structured 

file trees rooted at one or more places. See the FILES section for a description of the files 

and directories man should find in each directory that it searches. 

-T filelist 

specifies a list of .idx files to search before searching the files listed in MAN_TXT_INDEX 

when looking for a text version of a reference page. 

-w 

-x 

displays only the file name of the file containing the specified entry. 

displays the files that man is searching as it tries to find the entry. 

Search Rules 

To find a given entry, man follows a set of search rules. When you specify a type, man searches for 

the appropriate page amongst pages of that type; otherwise, man looks for the first page named 

entry regardless of the type. 

When the -h option is specified, man searches the .idx files listed in the MAN_CHM_INDEX 

environment variable for an entry matching the specified entry which indicates the HTML Help 

page in corresponding .chm to display. The HTML Help viewer is launched, displaying the page. 

Once you exit, the view, the man command exits. 

When -h is not specified, man takes the following steps to find the entry. Once a step results in 

11 of 457

finding the entry, man displays the reference page and exits. 

● man searches the .idx files listed in the MAN_TXT_INDEX environment variable for an 

entry matching the request entry which indicates the text (.txt) reference page to display. 

● man checks each directory in MANPATH for a file named man.dbz. If it exists, man looks for 

the requested entry in its index (see man.dbz File Format). 

● For each possible type (that is, type if you specified it, or all types in order from 1 through 9, 

then 0 if you did not): 

● man checks each directory in MANPATH for a file named catn/entry.n[l] where n 

is the type number, and l is the optional letter code. If it exists, man checks to see if it 

was compressed with pack, compress or mkszip, and uncompresses it (calling 

pcat if the file was packed). 

● man checks each directory in MANPATH for a file named mann/entry.n[l]. 

man.dbz File Format 

Sometimes, the reference pages are kept in a single large file, called man.dbz. The file starts with 

a magic text string: 

!\n 

and continues with the index: 

14 bytes formatted reference page name 

9 bytes seek pointer 

9 bytes length 

The name is simply the page name, followed by a dot and the type number. For example, this 

reference page would be named man.1. When man finds a matching entry, it seeks to the point in 

the file specified by the given seek pointer, and uncompresses for length bytes. Each reference 

page is compressed separately. 

EXAMPLES 

To find the utilities that do comparisons, type: 

man -k compar 

12 of 457

ENVIRONMENT VARIABLES 

MAN_CHM_INDEX 

contains a semicolon separated list of .idx files to search for entry when the -h is 

specified. 

MAN_TXT_INDEX 

contains a semicolon separated list of .idx files to search for entry when the -h is not 

specified. 

MANPATH 

contains a semicolon separated list of paths to search for reference pages. 

MANPAGER, PAGER 

contains an output filtering command for use when displaying reference pages on a 

terminal. 

TMPDIR 

identifies the directory where temporary files reside. 

FILES 

ROOTDIR/etc 

is the default directory for the online reference pages. The rest of the files listed here reside 

in this directory. 

cat[0-9]/*.[0-9] 

pre-formatted reference pages in normal, compressed, or packed form. 

man[0-9]/*.[0-9] 

unformatted reference pages. 

whatis 

is a database used by -k option. 

*.chm 

HTML Help files containing collections of reference pages complete with index, table of 

contents, and full text search. 

*.idx 

index files that man how to find HTML Help and text versions of individual reference files. 

13 of 457

The .idx files to search are indicated by the MAN_CHM_INDEX and MAN_TXT_INDEX 

environment variables. 

man.dbz 

is a master file containing all reference pages. 

The etc directory is found using the ROOTDIR environment variable. 

DIAGNOSTICS 

Possible exit status values are: 

0 

1 

Successful completion. 

Failure due to any of the following: 

PORTABILITY 

— unknown command line option 

— missing path after an -M option 

— no information available on the desired subject 

— unable to create a child process to format reference page 

— child process returned with non-zero exit status 

POSIX.2. x/OPEN Portability Guide 4.0. All UNIX systems. Windows Me. Windows NT 4.0. 

Windows 2000. Windows XP. Windows Server 2003. 

The -C, -h, -M, -T, -w, and -x options, the MANPAGER, MAN_CHM_INDEX, and 

MAN_TXT_INDEX environment variables, the default pager, the ability to specify type on the 

command line, and the ability to display reference pages in HTML Help format are all extensions to 

the POSIX and XPG standards. 

AVAILABILITY 

MKS Toolkit for Power Users 

MKS Toolkit for System Administrators 

MKS Toolkit for Developers 

MKS Toolkit for Interoperability 

MKS Toolkit for Professional Developers 

14 of 457

MKS Toolkit for Enterprise Developers 

MKS Toolkit for Enterprise Developers 64-Bit Edition 

MKS AlertCentre 

MKS Source Integrity Standard 

MKS Source Integrity Enterprise 

SEE ALSO 

Commands: 

help, manstrip, more 

15 of 457

si about 

displays product information 

SYNOPSIS 

si about [--[no]batch] [--cwd=directory] [(-g|--gui)] [--quiet] 

[--settingsUI=[gui|default]] [--status=[none|gui|default]] [(-?|--usage)] 

DESCRIPTION 

si about displays information about this copy of MKS Source Integrity. 

Options 

si about takes a subset of the universal options available to si commands. For example, 

si about --gui 

displays the product information in a GUI window. See the options reference page for 

descriptions. 

PREFERENCES 

Using si setprefs or si viewprefs, you are able to set or view the preference keys for this 

command. 

SEE ALSO 

Miscellaneous: 

diagnostics, options, preferences 

16 of 457

si acceptcp 

accepts change package 

SYNOPSIS 

si acceptcp [--comments=value] [--commentsFile=value] 

[--reviewer=[user|group:|super|all]] [--hostname=server] [--port=number] 

[--password=password] [--user=name] [(-?|--usage)] [(-Ffile|--selectionFile=file)] 

[(-N|--no)] [(-Y|--yes)] [--[no]batch] [--cwd=directory] [--forceConfirm=[yes|no]] 

[(-g|--gui)] [--quiet] [--settingsUI=[gui|default]] [--status=[none|gui|default]] 

issue|issue:change package id... 

DESCRIPTION 

si acceptcp casts an accept vote on a change package under review and in the submitted 

state. 

After a change package is submitted, each individual reviewer and one member of each reviewer 

group (if specified) in the reviewer list must accept the change package before it can be committed 

to the repository and then closed. 

If there are reviewers in addition to yourself, an e-mail is sent to notify those reviewers that you 

have cast an accept vote for the change package. 

When all of the individual reviewers and at least one reviewer from each reviewer group have 

accepted the change package, an e-mail is sent to notify the reviewers and the creator that the 

change package is accepted. 

Once the final required accept vote is cast, the change package is accepted and then committed to 

the repository. If the change package is successfully committed to the repository, it then moves to 

a state of Closed. If the change package fails to commit to the repository, the change package 

moves to a state of CommitFailed. Correct the error, then submit the change package again. 

If the change package under review is closed, an e-mail notification of the Closed state is sent to 

the change package watchers. All e-mail notifications contain Change Package and Review 

information. 

Options 

This command takes the universal options available to all si commands, as well as some general 

options. See the options reference page for descriptions. 

17 of 457

--comments=value 

specifies comments recorded in the review log with the vote. 

--commentsFile=value 

specifies a text file that contains the comments to be recorded in the review log with the 

vote. 

--reviewer=[user|group:|super|all] 

specifies the capacity in which you are casting an accept vote. 

user 

casts a vote as an individual reviewer in the reviewer list. 

group: 

casts a vote on behalf of the entire group (only one user from a group is necessary to 

vote on behalf of the entire group). 

super 

an overriding accept vote that is sufficient for accepting the change package even if 

there are additional reviewers. A super reviewer does is not required to be a listed 

reviewer for the change package. 

all 

casts a vote as a specific user and any group to which the reviewer belongs. 

issue... 

issue:change package id... 

issue identifies a specific issue that contains all submitted change packages that you want 

to cast accept votes for; use spaces to specify more than one issue. 

issue:change package id identifies a specific change package to cast an accept vote for; 

use spaces to specify more than one change package. 

DIAGNOSTICS 

See the diagnostics reference page for possible exit status values. 

PREFERENCES 



SEE ALSO 

Commands: 

si add, si ci, si co, si cpissues , si createcp, si drop, si lock, si 

viewcps, si rejectcp, si opencp, si discardcp, 

18 of 457


ACL, diagnostics, options, preferences 

19 of 457

si add 

adds a new member to a project 

SYNOPSIS 

si add [--archive=filename] [--author=name] [(--binaryFormat|--textFormat)] 

[(--cpid ID|--changePackageId=ID)] [--[no]defer] [--[no|confirm]closeCP] [--issueId=ID] [(ddesc|--description=desc)] 

[--descriptionFile=file] [--issueId=ID] [(-l|--lock)] 

[--onExistingArchive=[confirm|sharearchive|newarchive|cancel]] 

[--[no]createSubprojects] [--[no]retainWorkingFile] [--[no]saveTimestamp] 

[--[no]unexpand] [(-r rev|--revision=rev)] [(-R|--[no|confirm]recurse)] 

[(-S sandbox|--sandbox=sandbox)] [--hostname=server] [--port=number] [--password=password] 

[--user=name] [--cwd=directory] [(-F file|--selectionFile=file)] [--forceConfirm=[yes|no]] 

[(-g|--gui)] [(-N|--no)] [--[no]batch] [--quiet] [--settingsUI=[gui|default]] 

[--status=[none|gui|default]] [(-?|--usage)] [(-Y|--yes)] [-R|--[no|confirm]recurse] 

[--[no|confirm]includeFormers] [--exclude=file:pattern,dir:pattern...] 

[--include=file:pattern,dir:pattern...] nonmember... 

DESCRIPTION 

si add adds one or more nonmember files located in a sandbox directory to a project. 

For example, you can add a member from the c:\apps\prototype\ directory by specifying: 

si add --description="Prototype application header" 

-S prototype.pj header.c 

adds the header.c file to the project as a new member with the description "Prototype application header". 

Since the member is added to the project on the Source Integrity Server, all other users who have sandboxes 

pointing to the project can see the same new member. Source Integrity creates a history on the server for each 

newly added member that does not already have a history. 

If you intend to add files that already have a history, such as files you used in another project but wish to reuse 

in a new project, or a member that previously has been dropped (see si drop), then use the si 

addmemberfromarchive command. By default, if histories exist for members you add and you choose to 

attach the new members to them, Source Integrity creates a branch of the head revision. 

Adding a member that previously has been dropped (see si drop) results in the history of the dropped 

member becoming the history of the newly added member. 

Tip: To add existing members to a new project more quickly, place the files on the server and use the si 

import command. MKS recommends using the si import command for batch imports of a directory tree, 

or of history files from older versions of Source Integrity. 

Options 

20 of 457

This command takes the universal options available to all si commands, as well as some general options. See 

the options reference page for descriptions. 

--archive=filename 

sets the archive file name, filename, containing the server-side path and name by which the newly 

added member will be archived. This must be an existing archive file - this option does not create a new 

archive. This is an advanced option that effectively specifies an archive path to override the default 

mapping, allowing a basic form of archive sharing between projects; its use is not recommended except 

by advanced Source Integrity administrators. 

-r=value 

--revision=value 

Specifies the revision at which the member is to be added. By default, the member is added at the latest 

revision on the main branch. Values of 0.0 and 0.1 are acceptable revision numbers. The revision 

specified precludes specifying earlier revisions at a later date, for example after specifying 1.3, you 

cannot specify 1.2 as a valid revision. 

--author=name 

specifies an author name. 

--binaryFormat 

--textFormat 

forces the storage of the member file to occur in binary format or text format. This option overrides the 

preferences settings that control default behavior in the application for storage format. See the si 

setprefs and si viewprefs commands for more details on preferences. 

--cpid=ID 

--changePackageId=ID 

identifies a change package that is notified of this action, for example, 1452:1. Note the following about 

using this option: 

❍ This option can only be specified if change packages are enabled. 

❍ You must specify this option if you have requested to obtain a lock and TrackLocks is enabled, 

and/or it is mandatory to specify a change package. 

❍ If the integration is enabled, but it is not mandatory to specify a change package, or if no change 

package is applicable, you must specify --changePackageId=:none. 

--[no]defer 

controls whether to delay the add operation in the project until the deferred operation is submitted. The 

operation in the sandbox still takes place immediately. 

If the change package reviews are mandatory, specify the --deferred option to create a pending entry 

for this operation at the time of change package submission. If the --deferred option is not enabled, 

Source Integrity creates the pending entry at the completion of this procedure. When a deferred add 

member operation is submitted as part of a review, a pending member is created For more information, 

see the Source Integrity Enterprise User Guide. 

--[no|confirm]closeCP 

controls whether to close the associated change package. 

--nocloseCP means do not close the change package. 

--confirmcloseCP means ask before closing the change package. 

21 of 457

--closeCP always closes the change package. 

--issueId=ID 

identifies an MKS Integrity Manager issue that is notified of this action. This option is another way of 

adding members to a change package. If you have an issue assigned to you that contains one open 

change package, you can specify the issue ID instead of the change package ID. See the Integrity 

Server Administration Guide or your administrator for details on using the Integrity Manager integration. 

-l 

--lock 

controls whether to lock the newly created revision. 

--onExistingArchive=[confirm|sharearchive|newarchive|cancel] 

controls whether to allow sharing of this member's history between projects, or to create a new archive if 

there is already an existing archive for the member. 

--onExistingArchive=confirm means always ask whether to share the archive, create a new 

archive, or cancel the operation. 

--onExistingArchive=sharearchive means share the archive. 

--onExistingArchive=newarchive means create a new archive. 

--onExistingArchive=confirmsharearchive means always ask before sharing an archive. 

--onExistingArchive=confirmnewarchive means always ask before creating a new archive. 

--onExistingArchive=cancel means cancel the operation. 

--description=desc 

specifies a description for the new archive; this setting and the --descriptionFile option are 

mutually exclusive. If specifying a nonmember that has an existing history, this description does not 

overwrite an existing description and is ignored. 

Note: Descriptions that include spaces must be enclosed by quotes. 

-d desc 

--descriptionFile=file 

specifies a file for obtaining a description to apply to the new archive; this setting and the 

--description option are mutually exclusive. If specifying a nonmember that has an existing history, 

this description does not overwrite an existing description and is ignored. 

--[no]createSubprojects 

controls whether to create subprojects for each subdirectory encountered when adding members. This 

option is commonly used where you anticipate working with a large directory structure, because multiple 

subprojects are easier to manage than many subdirectories within one project. For example, specifying: 

si add --createSubprojects --description="Button Application" 

\buttons\activebutton.c 

creates a subproject for the \buttons directory and adds the file activebutton.c. Without the -createSubprojects 

option, the file and its path simply would be added to the project in the current 

directory. 

22 of 457

--[no]retainWorkingFile 

controls whether to retain a working file in the sandbox after adding the new member. 

--[no]saveTimestamp 

controls whether to set the revision timestamp to the modification date and time of the working file rather 

than the current date and time. 

--[no|confirm]includeFormers 

controls whether to include former members. Former members are members that have been dropped 

but whose working files still reside in the sandbox directory. 

--[no]unexpand 

controls whether to unexpand keywords in the member file before checking it into the history. Keyword 

expansion is only available in text archives, not binary archives. For descriptions of the Source Integrity 

keywords, see the Source Integrity User Guide. Possible keywords are: 

$Author$ 

$CompanyInfo$ 

$Date$ 

$Header$ 

$Id$ 

$Locker$ 

$Log$ 

$Name$ 

$ProjectName$ 

$ProjectSetting attribute$ 

$ProjectRevision$ 

$RCSfile$ 

$Revision$ 

$SandboxSetting attribute$ 

$Setting attribute$ 

$Source$ 

$State$ 

-R 

--[no|confirm]recurse 

controls whether to select non-members recursively. Non-members are files that exist in the sandbox 

directory but have not previously been added to the server repository. 

--exclude=file:pattern,dir:pattern... 

specifies a file that contains a glob pattern for excluding members. 

--include=file:pattern,dir:pattern... 

specifies a file that contains a glob pattern for including members. 

nonmember... 

identifies a specific file to add to your sandbox; use spaces to specify more than one. 

Note: All files must be added "in tree", that is, the nonmember must exist in the sandbox directory or a 

subdirectory. Shared "out of tree" histories are supported by using the --archive option to point to the 

"out of tree" history that you want to associate with the member. 

DIAGNOSTICS 

23 of 457


PREFERENCES 

Using si setprefs or si viewprefs, you are able to set or view the preference keys for this command. 

SEE ALSO 

Commands: 

si addmemberfromarchive, si import, si ci, si closecp, si co, si cpissues, si 

createcp, si drop, si projects, si sandboxes, si viewcps 



24 of 457

si addlabel 

assigns a label to project members 

SYNOPSIS 

si addlabel [--[no|confirm]moveLabel] [(-r rev|--revision=rev)] [(-L label|--label=label)] 

[(-R|--[no|confirm]recurse)] [--filter=filteroptions] [(-P project|--project=project)] 

[(-S sandbox|--sandbox=sandbox)] [--devpath=path] [--projectRevision=rev] [--hostname=server] 

[--port=number] [--password=password] [--user=name] [(-?|--usage)] 

[(-F file|--selectionFile=file)] [(-N|--no)] [(-Y|--yes)] [--[no]batch] [--cwd=directory] 

[--forceConfirm=[yes|no]] [(-g|--gui)] [--quiet] [--settingsUI=[gui|default]] 

[--status=[none|gui|default]] member... 

DESCRIPTION 

si addlabel assigns a label to a revision of one or more members of an MKS Source Integrity project. If you 

do not specify any members, the si addlabel command applies to all project members. 

Options 

This command takes the universal options available to all si commands, as well as some general options. See 

the options reference page for descriptions. 

--[no|confirm]moveLabel 

controls whether the application should move a label from one revision to another. 

--nomoveLabel disables the moving of a label. 

--confirmmoveLabel displays a confirmation message. 

--moveLabel moves the label. 

-L label 

--label=label 

identifies a label. To add the label "October 15th Prototype" to a member file activebutton.c, you 

would enter 

Note the following about using labels: 

si addlabel -L "October 15th Prototype" activebutton.c 

❍ Labels cannot contain colons(:), square brackets ([ ]), or leading spaces. 

❍ Labels cannot have the same format as a valid revision number. 

❍ Labels that include spaces must be enclosed by quotes. 

❍ MKS recommends not using hyphens (-) in labels. Using hyphens may cause some si commands to fail. 

❍ Labels cannot contain numbers without any spaces, for example, 14325. Numbers that contain spaces 

25 of 457

are acceptable, for example, 2432 1234. 

member... 

identifies a specific member; use spaces to specify more than one member. 

DIAGNOSTICS 


PREFERENCES 


SEE ALSO 

Commands: 

si addprojectlabel, si ci, si deletelabel, si deleteprojectlabel , si rlog, si 

viewlabels 



26 of 457

si addmemberattr 

adds attributes to a member 

SYNOPSIS 

si addmemberattr [(--attr=key[=value]|--attribute=key[=value])] 


[(-S sandbox|--sandbox=sandbox)] [--devpath=path] [--hostname=server] 





DESCRIPTION 

si addmemberattr adds attributes to a member, replacing any previous attribute of that same 

name specified with the member. If no members are specified, the command applies to all 

members of the project. 

Attributes are key-value pairs of strings that are associated with a member. They are used for 

automated operations. For example, you could have an attribute indicating the target operating 

system type: 

si addmemberattr --attr OS=WIN32 activebutton.c 

and then you could perform other operations, such as si resync, on just those files through the 

--filter universal option: 

si resync --filter=attribute:OS=WIN32 

Note: Attribute keys cannot contain a hyphen (-) as the first character. The first character must 

either be a underscore (_) or an alpha character. 

Options 



--attr=key[=value] 

--attribute=key[=value] 

sets the attribute key and, optionally, the value. Note: you cannot have commas (,) in the 

key or value, nor an underscore (_) at the beginning of an attribute. 

27 of 457

member... 


DIAGNOSTICS 


PREFERENCES 



SEE ALSO 

Commands: 

si addprojectattr, si dropmemberattr, si dropprojectattr 



28 of 457

si addmemberfromarchive 

adds a member from a server archive 

SYNOPSIS 

si addmemberfromarchive [--archive=value] [--[no]createSubprojects] [--[no]defer] 

[--[no|confirm]includeFormers] [--include=file:pattern,dir:pattern...] [--exclude=file:pattern,dir:pattern...] 

[--cpid|--changePackageId=value] [--[no|confirm]closeCP] [--issueId=value] [--devpath=value] 

[-P|--project=value] [-r|--revision=value] [-S|--sandbox=value] [--hostname=server] 

[--port=number] [--password=password] [--user=name] [(-?|--usage)] [(-Ffile|--selectionFile=file)] 

[(-N|--no)] [(-Y|--yes)] [--[no]batch] [--cwd=directory] [--forceConfirm=[yes|no]] [(-g|--gui)] [--quiet] 

[--settingsUI=[gui|default]] [--status=[none|gui|default]] nonmember... 

DESCRIPTION 

si addmemberfromarchive adds members from server archives. 

The si addmemberfromarchive command can be used for the following: 

● Add previously dropped members without requiring a sandbox working file, while preserving the member 

history. 

From the sandbox directory, for example, and assuming the three specified members have just been 

mistakenly dropped, the following command will re-add them: 

si addmemberfromarchive label.c button.c panel.c 

● Add a member that shares the history of another existing member, where the source member can be located 

in another project from the added member. 

From the sandbox directory, for example, the following command will add a member named largeLabel.c that 

shares the history with all members already linked to the specified archive location. 

si addmemberfromarchive --archive=/anotherproject/rcs/label.c largeLabel.c 

Note the following about the command: 

● can be deferred when performed from a sandbox 

● may be part of change package review (displayed as pending members in the project) 

● supports multiple selection of archives using the wizard 

Options 

This command takes the universal options available to all si commands, as well as some general options. See the 

options reference page for descriptions. 

--archive=value 

a non-default archive location (the specified archive must exist on the server). To add several members with 

29 of 457

non-default archive locations in one operation, use the GUI wizard (si addmemberfromarchive -g ). 

-r=value 


specifies the revision at which the member is to be added. This must be an existing revision in the archive. By 

default, the member is added at the latest revision on the main branch. 


controls whether to create subprojects for each subdirectory encountered when adding members. This option 

is commonly used where you anticipate working with a large directory structure, because multiple subprojects 

are easier to manage than many subdirectories within one project. For example, specifying: 

Application" 

si addmemberfromarchive --createSubprojects --description="Button 



option, the file and its path simply would be added to the project in the current directory. 

--[no]defer 

controls whether to delay the add member from archive operation in the project until the deferred operation is 

submitted. The operation in the sandbox still takes place immediately. 

If the change package reviews are mandatory, specify the --defer option to create a pending entry for this 

operation at the time of change package submission. If the --defer option is not specified, Source Integrity 

creates the pending entry at the completion of this operation. When a deferred import member operation is 

submitted as part of a review, a pending member is created For more information, see the Source Integrity 

Enterprise User Guide. 


controls whether to include former members. Former members are members that have been dropped but 

whose working files still reside in the sandbox directory. 





--cpid=value 


identifies a change package that is notified of this action, for example, 1452. Note the following about using 

this option: 


❍ You must specify this option if you have requested to obtain a lock and TrackLocks is enabled, and/or it 

is mandatory to specify a change package. 



❍ The next time you are prompted for a change package ID, the last used change package ID is 

displayed by default, if :none was specified or at least one change package was successfully updated 

from the last operation. 


closes the change package after command completion. 

--issueID=value 

specifies the issue ID that corresponds to the change package that records the changes. 

30 of 457

nonmember... 

identifies non-members to add; use spaces to specify more than one non-member. 

DIAGNOSTICS 


PREFERENCES 


SEE ALSO 

Commands: 

si add, si ci, si co, si cpissues , si createcp, si drop, si lock, si viewcps 



31 of 457

si addproject 

adds an existing project to the list of top-level projects 

SYNOPSIS 

si addproject [--[no]openView] [--hostname=server] [--port=number] 

[--password=password] [--user=name] [(-?|--usage)] [(-F file|--selectionFile=file)] 



[--[no]add] project location... 

DESCRIPTION 

si addproject adds an existing project to the list of top-level projects. 

The si addproject command can be used for the following: 

● Expose an existing subproject as a top-level project. 

● Expose a project imported with the --noadd flag. 

● Re-expose a dropped top-level project. 

Note: This command actually has to perform a processing very similar to the ImportProject 

command. This is why those two commands share the ImportProject ACL. 

MKS suggests you use si Addproject when the project is already in the Source Integrity 

repository and si ImportProject when importing projects from older versions of Source 

Integrity. 

Options 



--[no]openView 

controls whether to open the project view after this project is added. If --noopenView is 

used, the project view does not open. 

project location... 

identifies a location on the Integrity Server for the existing project to be added. Regardless 

of your operating system, all paths are specified here using forward slashes (/) and should 

include the name of the project file (typically project.pj). Use spaces to specify more 

than one project location. 

32 of 457

DIAGNOSTICS 


PREFERENCES 



SEE ALSO 

Commands: 

si checkpoint, si createproject, si createsandbox, si createsubproject, 

si dropproject, si addsandbox, si projects, si importproject, si 

viewproject 



33 of 457

si addprojectattr 

adds attributes to a project 

SYNOPSIS 

si addprojectattr [(--attr=key[=value]|--attribute=key[=value])] 





[--settingsUI=[gui|default]] [--status=[none|gui|default]] 

DESCRIPTION 

si addprojectattr adds attributes to a project, replacing any previous attribute of the same 

name specified with the project. 

Attributes are key-value pairs of strings that are associated with the project. They are used for 

automated operations. For example, you could have an attribute indicating the target operating 

system type: 

si addprojectattr --attr OS=WIN32 



Options 



--attr=key[=value] 

--attribute=key[=value] 

sets the attribute key and, optionally, the value. Note: you cannot have commas (,) in the 

key or value, nor an underscore (_) at the beginning of an attribute. 

DIAGNOSTICS 


34 of 457

PREFERENCES 



SEE ALSO 

Commands: 

si addmemberattr, si dropmemberattr, si dropprojectattr, si 

dropsandboxattr, si addsandboxattr 



35 of 457

si addprojectlabel 

assigns a label to a project 

SYNOPSIS 

si addprojectlabel [--[no|confirm]moveLabel] [(-L label|--label=label)] 


[--projectRevision=rev] [--hostname=server] [--port=number] [--password=password] 

[--user=name] [(-?|--usage)] [(-Ffile|--selectionFile=file)] [(-N|--no)] [(-Y|--yes)] 

[--[no]batch] [--cwd=directory] [--forceConfirm=[yes|no]] [(-g|--gui)] [--quiet] 


DESCRIPTION 

si addprojectlabel assigns a label to a checkpointed revision of a project. 

Options 








-L label 

--label=label 

identifies a label. Note the following about using labels: 




❍ MKS recommends not using hyphens (-) in labels. Using hyphens may cause some 

si commands to fail. 

❍ Labels cannot contain numbers without any spaces, for example, 14325. Numbers 

that contain spaces are acceptable, for example, 2432 1234. 

36 of 457

DIAGNOSTICS 


PREFERENCES 



SEE ALSO 

Commands: 

si addlabel, si ci, si deletelabel, si deleteprojectlabel , si rlog, si 

viewlabels 



37 of 457

si addsandboxattr 

adds sandbox attributes 

SYNOPSIS 

si addsandboxattr [--attr|attribute=key=value] [-S|--sandbox=value] 


[(-?|--usage)] [(-Ffile|--selectionFile=file)] [(-N|--no)] [(-Y|--yes)] [--[no]batch] 



DESCRIPTION 

si addsandboxattr adds sandbox attributes. 



Options 



--attr=key=value 

--attribute=key=value 

specifies the attibute to set. 

DIAGNOSTICS 


PREFERENCES 



SEE ALSO 

Commands: 

38 of 457

si dropsandboxattr, siconfiguresandbox, add projectattr, 

dropprojectattr 



39 of 457

si addsubproject 

adds an existing subproject to a project 

SYNOPSIS 

si addsubproject [-r subproject revision|--subprojectRevision=subproject revision] 

[--subprojectDevelopmentPath=subproject development path name|--variant=subproject development path 

name] [--type=[normal|variant|build|default]] [(-Pproject|--project=project)] 

[(-S sandbox|--sandbox=sandbox)] [--devpath=path] [--hostname=server] [--port=number] 

[--password=password] [--user=name] [(-?|--usage)] [(-F file|--selectionFile=file)] [(-N|--no)] 

[(-Y|--yes)] [--[no]batch] [--cwd=directory] [--forceConfirm=[yes|no]] [(-g|--gui)] [--quiet] 

[--settingsUI=[gui|default]] [--status=[none|gui|default]] subproject location... 

DESCRIPTION 

si addsubproject allows you to re-add a dropped subproject to recreate an earlier version of the project. 

Note: If you want to add a normal subproject to a variant project, the normal subproject does not require a 

development path. 

Options 



-r=subproject revision 

--subprojectRevision=subproject revision 

specifies the revision number (for build subprojects). For example, 1.5. This option is used with -type=build. 

--subprojectDevelopmentPath=subproject development path name 

--variant=subproject development path name 

specifies the development path name (for variant subprojects). For example, Service_Pack3. This option is 

used with --type=variant 

--type=[normal|variant|build|default] 

specifies the new configuration type for the subproject. 

--type=normal configures the subproject based upon the current state of the subproject. 

--type=variant configures the subproject based upon a specific development path. The option is used 

with --variant=subproject development path name or --subprojectDevelopmentPath=subproject 

development path name. 

--type=build configures the subproject as a static subproject based upon a specific revision of the master 

project that is used for building or testing the project, but not for further development. This option is used with - 

r subproject revision or --subprojectRevision=subproject revision. 

--type=default configures the subproject based on the type that is consistent with the parent project that 

you are adding the subproject to. For example, if you add a subproject to a normal project, the subproject is 

added as a normal type. For information on what the default type is, see your administrator. 

-P project name 

40 of 457

--project=project name 

specifies the path and name of the project to add the subproject to, for example, 

c:/Aurora_Program/bin/project.pj. 

subproject location... 

specifies the path and name of the subproject you want to add, for example, 

c:/Aurora_Program/bin/Libra/project.pj 

DIAGNOSTICS 


PREFERENCES 


SEE ALSO 

Commands: 

si checkpoint, si configuresubproject , si createproject , si createsandbox , si drop, 

si dropproject, si importproject, si projectinfo, si projects, si sharesubproject, si 

viewproject 



41 of 457

si annotate 

displays an annotated revision. 

SYNOPSIS 

si annotate [--[no]defaultFormat] [--[no|un]expand] 

[--fields=field1[:width1],field2[:width2]...] [-height=value] [-width= value] [-x=value] 

[-y=value] [-r|--revision=value] [--devpath=value] [-P|--project=value] 

[-S|--sandbox=value] [--projectRevision=value] [--hostname=server] [--port=number] 

[--password=password] [--user=name] [(-?|--usage)] [(-N|--no)] [(-Y|--yes)] 


[--settingsUI=[gui|default]] [--status=[none|gui|default]] member 

DESCRIPTION 

si annotate displays an annotated revision. Use the command when you want to know the 

reason and circumstances a line was introduced or changed. Rather than viewing the content of 

each revision in the history one revision at a time, you can see the line by line history that includes 

information on a per revision basis. 

Options 



--[no]defaultFormat 

specifies if the default format is used to display the output. 

--[no|un]expand 

specifies if the keywords are expanded in the output. 

--fields=field1[:width1],field2[:width2]... 

The fields available for printing can be one or more of the following: 

author 

displays the author of the revision. 

cpid 

displays the line's associated change package ID. 

date 

displays the date each line in the history was created. 

labels 

displays revision labels. 

linenum 

42 of 457

displays the line number for each line of text in the revision.. 

revision 

displays the line's revision number. 

text 

displays the text contained in the line. 

--height=value 

specifies the height in pixels of the window. 

--width=value 

specifies the width in pixels of the window. 

--x=value 

specifies the x location in pixels of the window. 

--y=value 

specifies the y location in pixels of the window. 

-r|--revision=value 

specifies the revision number to view. 

--devpath=value 

selects the revision of the member on a specified development path. Can also be used to 

specify the development path the revision is on, which is used to refer to variant projects. 

-P|--project=value 

specifies the name of the target project. 

-S|--sandbox=value 

specifies the name of the sandbox and can be used as project redirector. 

--projectRevision=value 

specifies the project revision number and can be used to refer to build projects. 

member 

specifies the name of the member to view. 

DIAGNOSTICS 


PREFERENCES 



SEE ALSO 

Commands: 

si archiveinfo, si memberinfo, si mods, si print, si revisioninfo, si 

rlog, si sandboxinfo, si viewhistory, si viewlabels, si 

43 of 457

viewprojecthistory, si viewsandbox 



44 of 457

si appendrevdesc 

appends additional text to a revision description 

SYNOPSIS 

si appendrevdesc [(-d desc|--description=desc)] [--descriptionFile=file] 

[(-r rev|--revision=rev)] [(-R|--[no|confirm]recurse)] [--filter=filteroptions] 



[--user=name] [(-?|--usage)] [(-F file|--selectionFile=file)] [(-N|--no)] [(-Y|--yes)] 



DESCRIPTION 

si appendrevdesc appends additional text to a revision description. A revision description is 

created when you check in a new revision. When you review the description for a specific revision, 

through the si viewhistory command, you see the appended information in a manner similar 

to the following: 

Options 

--- Added comments --- sholmes [2002/07/20 20:23:55Z] 

Appended Description 



-d desc 


specifies the new description text to be appended to the existing revision description. These 

options and the --descriptionFile option are mutually exclusive. 

Note: 

Descriptions that include spaces must be enclosed by quotes. 


specifies a file name, file, containing the new description text to be appended to the existing 

revision description. This option and the -d or --description options are mutually 

exclusive. 

member... 


45 of 457

DIAGNOSTICS 


PREFERENCES 



SEE ALSO 

Commands: 

si addlabel, si archiveinfo, si ci 



46 of 457

si applycp 

applies one or more change packages to a Source Integrity project 

SYNOPSIS 

si applycp [--[no]alreadyInProjectIsError] 

[--backFill=[cp|revision|error|skip|ask]] [--[no|confirm]closeCP] 

[--[no]confirm] [--[no|confirm]createVariants] [--[no]ignoreBranches] 

[--[no]ignoreServer] [--[no]otherProjectIsError ] [--[no]spanProjects] 

[--[no]verbose] [(-P project|--project=project)] [(-S sandbox|--sandbox=sandbox)] 

[--devpath=path] [--hostname =server] [--port=number] [--password=password] 

[--user=name] [(-?|--usage)] [(-F file|--selectionFile=file)] [(-N |--no)] [(-Y|--yes)] 

[--[no]batch] [--cwd =directory] [--forceConfirm=[yes|no]] [(-g|--gui)] [--quiet] 


[--cpid|--changePackageID=value] [--[no]ignoreUpdateRevision] [--issueID=value] 


DESCRIPTION 

si applycp applies one or more change packages to a Source Integrity project, incorporating 

only the changes you want. 

Feature Overview 

A change package specifies groups of members that are affected by an issue. An issue tracks 

changes that occur during the development process. An example of a change package would be a 

group of files that need to be changed to address a problem in program code. 

Both Apply CP and Resync CP rely on the use of change packages to track individual changes that 

modify project content or create new content. If a development team has been using change 

packages consistently, Source Integrity can isolate all changes related to a specific issue because 

this information is recorded as part of the change package. Once the dependencies are calculated, 

the operation completes and the change packages are applied in the project. 

If a development team does not use the change package methodology, isolating specific content 

becomes a complex, manual task. In a large code project, this could mean searching hundreds of 

files to determine which ones are related to a specific issue. To build the project, it would then be 

necessary to add, drop, rename, and move files, update file revisions, merge around unwanted 

revisions, merge in required changes, and merge out any unwanted changes. 

Using the functionality of Apply CP and Resync CP, this complicated process becomes largely 

automated. In Source Integrity, the Apply CP operation adds, drops, renames, and moves files, 

47 of 457

and updates file revisions as required to create the desired change. If merging is required, you can 

use the Resync CP command. Resync CP allows you to either merge in desired changes or merge 

around unwanted changes. 

Apply CP and Resync CP are most useful for code and other text files where differencing can be 

performed. 

The Change Package Methodology 

When used across a development project, Apply CP and Resync CP are powerful tools for 

managing changes and new content. However, the effectiveness of the functionality ultimately 

relies on the following factors: 

● accurate and consistent logging of issues into the Integrity Manager database 

● associating related changes into a single change package that ultimately addresses the 

issue in question 

Because issues, and their associated change packages, follow a workflow progression, it is critical 

that each member of the development team record and track all changes as they are made, from 

the initial phase to the completion phase in which the associated problem is addressed. All 

changes relating to a given issue must then be associated with the correct change package. Once 

the problem is addressed, or the feature added, that change package can be closed. 

It is equally important that issues are clearly delineated so that each change package addresses 

only one problem area or feature. Certainly, one problem area or feature may require many files to 

address it, but if you create a change package that is too wide in scope, it becomes difficult to 

extract specific changes later on. 

With accurate and consistent logging, Source Integrity can clearly identify the specific member 

revisions (or files) that address the identified problem or complete the required feature. Without this 

type of tracking, applying a change package may not have the desired results and manual reviews 

may become necessary. 

The Commands 

Consider the following scenario at abcBusiness--a major customer purchased version 2.0 of 

abcBusiness' Aurora software. The customer now wants a new feature--data compression--that 

they can use with Aurora 2.0 The development team at abcBusiness has already completed work 

on a data compression feature, bu the feature has been engineered only as part of the upcoming 

Aurora 3.0 release. 

To address the customer's needs, abcBusiness would normally have to assign a separate 

development team to create the new feature for Aurora 2.0 But how can abcBusiness take 

advantage of the work already completed on the data compression feature and provide it to the 

48 of 457

customer? 

If the development team has been using change packages, they can isolate the files that relate to 

the new data compression feature. However, without the functionality of Apply CP and Resync CP, 

the buildmaster at abcBusiness would have to manually search the required change package(s) 

and individually review all of the associated files to isolate the changes related to the feature. The 

buildmaster would then have to manually add, drop, rename, and move files, update file revisions, 

merge around unwanted revisions, merge in required changes, and merge out any unwanted 

changes. 


automated. In Source Integrity, the Apply CP operation works directly in the project to add and 

drop files, and update file revisions as required to create the desired change. Source Integrity 

presents you with a list--the backfill list--of all change packages required to capture the issue. In 

the Apply CP operation, you must either accept or decline this list--you cannot make selections. If 

you accept the list, the Apply CP command completes. If you decline the list, the Apply CP 

command cannot complete. 

If the Apply CP command fails because merging is required, you can then run the Resync CP 

command. Resync CP works in a sandbox and allows you to make selections from the backfill list. 

Source Integrity then merges around unwanted changes and uses differencing to merge files. 

Consider once again, the abcBusiness development team. Because the team has been tracking all 

of their changes through the use of change packages, they can target the main trunk of 

development and use Apply CP and Resync CP functionality to extract only those files that relate 

to the new data compression feature. Those specific change packages can then be applied to a 

variant project of Aurora 2.0 and testing carried out within a new project designed specifically for 

the customer. 

The functionality allows you to maximize existing development work, while being more responsive 

to both internal and external stakeholders. Apply CP and Resync CP are especially effective in any 

environment where there are large numbers of files to deal with--whether these are code files for a 

software project or Web pages for a complex Web site. 

Apply CP Example 

This section provides an example to show how Apply CP can be used in your environment. In this 

example, the buildmaster brings a new feature from the main trunk of project development and 

applies it to an earlier release. 

The abcBusiness software company has released their Aurora software, version 3.0. When the 

release was completed, the project was checkpointed and all project members were labelled. The 

development team is now working on a new set of features for the next release, 4.0. A new feature 

for this release is a timestamp function. All the changes associated with the timestamp function 

49 of 457

have been recorded in a change package, or set of issues, that isolates the feature from other 

features. 

Now abcBusiness receives a request from a customer who has Release 3.0 but also needs the 

new timestamp feature for its global operations. The code in development for Aurora 4.0 is not 

stable enough for release and too many resources would be required to accelerate the release 

schedule. How can abcBusiness provide the timestamp feature without affecting the current 

release? Because the code for this feature is isolated within a change package, the Apply CP 

command can be used to transfer the feature to the earlier, stable release. 

The buildmaster at abcBusiness would: 

● create a variant project off of the checkpoint for version 3.0. This variant project is isolated 

from the rest of the development team so that unwanted changes are not added to the main 

trunk of the development path. 

● use Apply CP to apply the change package to the variant project. The change package 

contains all the files that were changed or added to produce the timestamp feature. Apply 

CP is essentially adding the feature to the variant of Aurora 3.0. 

● create an executable of the software. 

That executable can then be tested by Quality Assurance and shipped to the customer. 

Using Apply CP 

Apply CP relies on the use of change packages to track individual changes that modify project 

content or create new content. The Apply CP operation presents you with a backfill list that 

includes all of the change packages required for the identified issue. If you accept the backfill list, 

the operation then adds, drops, renames, and moves files, and updates file revisions as required to 

create the feature, content, or bug fix you are looking for. 

How Does Apply CP Work? 

The Apply CP operation applies change packages through a revision process. By applying a 

change package, you can incorporate only those changes that you want to include in the project. 

The Apply CP operation reads the entries in a change package and updates the project to the 

revisions listed in that change package. This function of the command is an automated process of 

the Update Revision command (si updaterevision). The Apply CP operation may also require 

that files be added, dropped, renamed, or moved. This function of the command is an automated 

process of the Add Member command (si add), the Drop Member command (si drop), the 

Rename Member command (si rename), and the Move Member command (si move). 

Note: If reviews are mandatory, the changes made by an Apply CP operation must be recorded as 

pending entries in a change package. The change package must be then submitted, which starts 

50 of 457

the review process. For more information on the review process, see the Source Integrity 

Enterprise User Guide. 

When Should I Use the Apply CP Command? 

You should use the Apply CP command when you need to update a project to include changes 

listed in a change package. The updating process updates member revisions, and may also 

involve adding, dropping, renaming, and moving files. The Apply CP command is most useful for 

building software. 

Are There Any Limitations When Using Apply CP? 

The Apply CP operation adds, drops, renames, and moves files, and updates file revisions. Apply 

CP does not automatically manage subprojects, for example, it does not delete or remove 

subprojects and cannot detect the user’s intentions with respects to handling them. Apply CP only 

operates on closed change packages and cannot perform merging. The operation is carried out in 

relation to the project. If you run the Apply CP command from a sandbox, the sandbox acts as a 

redirector to the project. 

For more detailed information and examples on si applycp, see the Source Integrity Enterprise 

User Guide. 

Options 



--[no]alreadyInProjectIsError 

Causes Source Integrity to terminate the operation if the member being resynchronized is 

the same one listed in the change package and is already in the project. If this setting is 

negated --noalreadyInProjectIsError, then the information is displayed as a 

warning. 

--backFill=[cp|revision|error|skip|ask] 

Specifies the way Source Integrity treats historic revisions required by the specified change 

package. 

--backFill=cp 

recursively chooses all historic revisions required by the specified change packages 

and applies them by updating member revisions, adding files, or dropping files. 

--backFill=revision 

processes only the specified change package(s) and chooses only directly associated 

revisions. It does not process any change packages that are associated with 

intermediate revisions. 

--backFill=error 

terminates the operation if other change packages are required but are not specified. 

51 of 457

--backFill=skip 

causes Source Integrity to merge around backfill revisions. 

--backFill=ask 

allows you to specify the change packages you want to include. 

--[no]confirm 

specifies whether to confirm the actions before starting them. 

--[no|confirm]createVariants 

specifies whether to create variant projects within the target project as required to apply the 

change package members. 

--[no]ignoreBranches 

specifies whether to use the most recent revision when Source Integrity encounters two 

revisions of the same member on different branches in the change package being applied. 

--[no]ignoreServer 

specifies whether to perform the Apply CP operation even if the change package members 

reside on different servers. 

Note: If you specify --ignoreServer, you must also specify --otherProjectIsError. 

This additional setting is required because projects are defined by their server and path. 

--[no]ignoreUpdateRevision 

ignores update revision change package entries. Use this option when the change package 

contains backward revision updates, for example, from 1.4 to 1.2. The default is to include 

update revision entries. 

--[no]otherProjectIsError 

specifies whether to terminate the command if any member in a change package is in 

another project. Change package entries referring to other projects are therefore treated as 

an error. 

--[no]spanProjects 

specifies whether to apply the command to any member specified in the change package, 

even if this involves multiple projects. If you are applying a change package that contains 

move member entries, the --[no]spanProjects option must be used. 

Warning: This is the only operation that has the potential to affect other projects. 

--[no]verbose 

specifies whether to include additional information to track the current state of the command. 

--cpid=value 


identifies a change package that is notified of this action, for example, 1452. This option is 

mandatory if change package reviews are mandatory. 

Note the following about using this option: 


❍ You must specify this option if you have requested to obtain a lock and TrackLocks is 

enabled, and/or it is mandatory to specify a change package. 

52 of 457

❍ If the integration is enabled, but it is not mandatory to specify a change package, or if 

no change package is applicable, you must specify --changePackageId=:none. 

❍ The next time you are prompted for a change package ID, the last used change 

package ID is displayed by default, if :none was specified or at least one change 

package was successfully updated from the last operation. 





issue... 


issue identifies a specific issue that contains all change packages that you want to include; 

use spaces to specify more than one issue. 

issue:change package id identifies a specific change package to include; use spaces to 

specify more than one change package. 

DIAGNOSTICS 


PREFERENCES 



SEE ALSO 

Commands: 

si resync, si resynccp 



53 of 457

si archiveinfo 

displays information about an archive 

SYNOPSIS 

si archiveinfo [--[no]labels] [--[no]locks] [(-P project|--project=project)] 

[(-S sandbox|--sandbox=sandbox)] [--devpath=path] [--projectRevision=rev] 


[(-?|--usage)] [(-N|--no)] [(-Y|--yes)] [--[no]batch] [--cwd=directory] 



DESCRIPTION 

si archiveinfo displays global information about an archive. It does not contain any perrevision 

information. For example: 

Member Name: c:\Documentation\Man_Pages\xml_man\si_add.1.xml 

Sandbox Name: c:\Documentation\Man_Pages\project.pj 

Archive Name: \rd\doc\Man_Pages\xml_man\rcs\si_add.1.xml 

Archive Type: Text 

Shared 

Strict Locking 

Archive Description: 

Labels: 

TechReview1 1.7 

PeerReview_1 1.6 

Note: Shared displays only if other members share the archive and you are using the database 

repository. 

Options 



--[no]labels 

controls whether to show labels and associated revision IDs. 

--[no]locks 

controls whether to show locks and associated revision IDs. 

member... 


54 of 457

DIAGNOSTICS 


PREFERENCES 



SEE ALSO 

Commands: 

si memberinfo, si mods, si revisioninfo, si rlog, si viewhistory, si 

viewlabels 



55 of 457

si checkpoint 

checkpoint archives in a project 

SYNOPSIS 

si checkpoint [--author=name] [(-d desc|--description=desc)] 

[--descriptionFile=file] [--[no]labelMembers] [--[no]notify] 

[(-L label| --label=label)] [(-s state|--state =state)] [--[no]stateMembers] 





[--status=[none|gui|default]] 

DESCRIPTION 

Just as you check in a source file to preserve the changes made to it from one revision to another, 

you can also track the evolution of an entire project. In Source Integrity, this process is called 

checkpointing. 

Checkpointing a project creates a new revision of the project and adds it to the project history. 

When you checkpoint a project, you save all the information needed to recreate the project 

completely at any time in the future. The saved information includes the project structure and the 

list of members with their revision numbers. 

If you are using the database repository, all checkpoints are transactional. This means that a 

checkpoint records the structure and contents of the project at the time the checkpoint starts. It 

does not include anything added to the project or its subprojects after the checkpoint starts, such 

as check ins or submitted change packages. To ensure that only complete change packages are 

included in your project checkpoints, your administrator must enable change package reviews. For 

more information on change package reviews, see the Source Integrity Enterprise User Guide. 

Note: 

Options 

Checkpointing a project recursively checkpoints all subprojects, creating new subproject 

revisions. If you do not want to create new subproject revisions during the checkpoint, 

configure them as build subprojects first. See the si configuresubproject command 

for more details. 



56 of 457

--author=name 

specifies an author name to identify the author of the new revision. 

-d desc 


specifies a description for the checkpointed revisions. These options and the 

--descriptionFile option are mutually exclusive. 

Note: 



specifies a file name, file, containing the description text for the checkpointed revisions. This 

option and the -d or --description options are mutually exclusive. 

--[no]labelMembers 

controls whether to label the members in addition to the project. If labelMembers is 

specified, labels are always moved to the revision, even if they already exist on another 

revision. Each member is labeled at the member revision. 

Note: 

While using this option is not necessary in order to reconstruct the state of a project 

at a later date, some sites find this option useful for such an action. 

--[no]notify 

controls whether to notify when the checkpoint is complete. 

-L label 

--label=label 

identifies a label. The label is applied to the checkpointed revision of the project, and to all 

members if --labelMembers is specified. Note the following about using labels: 






-s state 

--state=state 

specifies a state, state, for the checkpointed revisions. The state is applied to the 

checkpointed revision of the project, and to all members if --stateMembers is specified. 

--[no]stateMembers 

controls whether to set the state for members at member revision, in addition to the project. 

DIAGNOSTICS 


57 of 457

PREFERENCES 



SEE ALSO 

Commands: 

si addprojectattr, si addprojectlabel, si ci, si createdevpath, si 

createproject, si createsubproject, si importproject, si memberinfo, si 

projectinfo, si projects, si promoteproject, si setprojectdescription, 

si viewproject, si viewprojecthistory 



58 of 457

si ci 

checks in members of a sandbox 

SYNOPSIS 

si ci [--[no|confirm]ignoreUnresolvedMerge] [(-L label|--label=label)] 

[--author=name] [--[no]branch] [--[no|confirm]branchUpdate] 

[(--cpid ID|--changePackageId=ID)] [--issueId=ID] 

[--[no|confirm]checkinUnchanged] [--[no|confirm]closeCP] 

[(-d desc|--description=desc)] [--[no]defer] [--descriptionFile=file] 

[--issueId=ID] [(-l|--[no]lock)] [--[no|confirm]moveLabel] 

[(-r rev|--revision=rev)] [--[no]retainWorkingFile] [--revision=value] 

[--[no]saveTimestamp] [(-u|--unlock)] [--[no]unexpand] [--[no]update] 

[(-R|--[no|confirm]recurse)] [--filter=filteroptions] [(-S sandbox|--sandbox=sandbox)] 


[(-?|--usage)] [-F value] [(-N|--no)] [(-Y|--yes)] [--[no]batch] [--cwd=value] 

[--forceConfirm=[yes|no]] [--selectionFile=value] [(-g|--gui)] [--quiet] 

[--settingsUI=[gui|default]] [--status=[none|gui|default]] sandbox member... 

DESCRIPTION 

si ci checks in and saves changes to sandbox members. If you do not specify any members, si 

ci applies to all members of an associated sandbox. 

Check in is an operation that adds a new revision of a file to an archive. When a file is checked in 

to a revision other than the head revision or a branch tip revision, a new branch is created. 

Assigning Revision Numbers 

By default, when you check in a member, Source Integrity automatically assigns a unique revision 

number to the new revision. It does this by incrementing the current revision number by one. For 

example, if the previous revision is 1.3, the new revision is assigned number 1.4. 

You can choose the revision number of the changes you are checking in, so long as your revision 

number: 

● is greater than the last revision number (you cannot use previously "skipped" revision 

numbers) 

● has no leading zeros (zeros as complete revision numbers are acceptable) 

● starts a new branch based on an existing revision 

59 of 457

If you check in a revision using an already existing revision number, Source Integrity attempts to 

add one to the revision number and check it in as that revision. If that revision already exists, 

Source Integrity then chooses the next available branch number and creates a new branch. 

For example, if you are checking in a new revision to an archive where the head revision is 1.7, the 

following numbers are valid: 

● 1.8 (greater than head revision)--if you check in a revision as 1.7, which already exists, 

Source Integrity assigns it 1.8 

● 1.10 (greater than head revision) 

● 1.72 (none of the numbers between 7 and 72 may be used afterwards) 

● 2.0 

● 1.7.1.1 (if it starts a new branch) 

● 1.7.0.1 (leading zero as the branch number) 

The following numbers are invalid: 

● 1.3 even if there was no revision 1.3 previously 

● 1.08 (leading 0 in last portion) 

● 02.1 is considered the same as 2.1 (leading zero in branch number) 

Options 



--[no|confirm]ignoreUnresolvedMerge 

controls whether to ignore a previously unresolved merge. For more information on merging 

revisions, see si merge and si mergebranch. 

-L label 

--label=label 

identifies a label that is applied to the new revision. Note the following about using labels: 






--author=name 


--[no]branch 

controls whether to force the creation of a branch revision. 

60 of 457

A branch is a revision path that diverges from the main line of development (also known as 

the trunk) in a member or project history. A branch is typically created by checking in a file 

to a revision other than the head revision. The most recent revision of a branch is called the 

tip revision. 

MKS Source Integrity usually places new revisions at the top of the trunk, assigning them 

two-part revision numbers, such as 1.15. There are times, however, when you do not want 

your work to be checked into the trunk. You may be pursuing a line of development that will 

not be included in the finished product, for instance, or you may be doing post-release 

maintenance while development for the next release continues on the trunk. 

Divergent lines of development in the same archive are managed through the use of 

branches. A branch is an independent revision line that uses an existing revision as its 

starting point. Members of a branch revision are identified by their revision numbers. 

Whereas revisions on the trunk are characterized by two-part revision numbers (for 

example, 1.2 or 3.5), branch revision numbers are prefixed with the number of the revision 

they start from. For example, if a branch revision is started from revision number 1.2, the 

members of that branch are numbered 

1.2.1.1 

1.2.1.2 

1.2.1.3 

and so on. The first two digits of the number identify the revision where the branch diverges from 

the trunk, and the last two represent a position on the branch. 

--[no|confirm]branchUpdate 

controls whether to update the member revision, even if it is on a branch. This option stops 

the member revision from accidentally moving onto a branch if a branch was created during 

check out. This option only applies if --update is specified, --revision was not 

specified, and the member revision is on a different branch from the working revision. 

--nobranchUpdate means do not update the member revision. 

--confirmbranchUpdate means ask before updating the member revision. 

--branchUpdate always updates the member revision. 

--cpid=ID 


identifies a change package that is notified of this action, for example, 1452. Note the 

following about using this option: 

61 of 457




❍ If you have TrackLocks enabled, Source Integrity prompts you with the change 

package you used when you checked out the specified member, not the default 

change package. From the graphical user interface, you must manually select the 

change package. 

❍ If it is not mandatory to specify a change package, or if no change package is 

applicable, you must specify --changePackageId=:none. 




--issueId=ID 

identifies an MKS Integrity Manager issue that is notified of this action. This option is 

another way of adding members to a change package. If you have an issue assigned to you 

that contains one open change package, you can specify the issue ID instead of the change 

package ID. See the Integrity Server Administration Guide or your administrator for details 

on using the Integrity Manager integration. 

--[no|confirm]checkinUnchanged 

controls whether to force the checkin so that the new revision is checked in even if it is not 

different from the preceding one. 

--nocheckinUnchanged means do not force the checkin. 

--confirmcheckinUnchanged means ask before forcing the checkin. 

--checkinUnchanged always forces the checkin. 






-d desc 


specifies a description for the new revision. This option and the --descriptionFile 

option are mutually exclusive. 

Note: 


--[no]defer 

62 of 457

controls whether to delay the checkin operation in the project until the deferred operation is 


If reviews are mandatory, specify this option to submit the changes for review as a change 

package. If this option is not specified, a pending revision is created for the operation, that 

corresponds to a pending entry in the change package. 


specifies a file name, file, containing the description text for the new revision. This option 

and the -d or --description options are mutually exclusive. 

-l 

--[no]lock 

controls whether to keep locks on members. 






--[no]retainWorkingFile 

controls whether to keep the working file in the sandbox after checkin. By default, a sparse 

sandbox does not retain the working file after checkin. 

--[no]saveTimestamp 

controls whether to set the revision timestamp to the modification date and time of the 

working file rather than the current date and time. 

-u 

--unlock 

unlocks the newly checked-in revision. This is equivalent to specifying --nolock. 


controls whether to expand, unexpand, or ignore keywords in the member file. Keyword 

expansion is only available in text archives, not binary archives. For descriptions of the MKS 

Source Integrity keywords, see the Source Integrity Enterprise User Guide. Possible 

keywords are: 

$Author$ 

$CompanyInfo$ 

$Date$ 

$Header$ 

$Id$ 

$Locker$ 

$Log$ 

$Name$ 

63 of 457

$ProjectName$ 



$RCSfile$ 

$Revision$ 



$Source$ 

$State$ 

--[no]update 

controls whether to set the checked in revision as the project's member revision. 

sandbox member... 


DIAGNOSTICS 


PREFERENCES 



SEE ALSO 

Commands: 

si closecp, si co, si cpissues, si createcp, si diff, si edit, si lock, si 

mergebranch , si rlog, si unlock, si viewcps 



64 of 457

si closecp 

closes a change package. 

SYNOPSIS 

si closecp [--[no|confirm]allowOrphanedDeferred] [--[no]confirm] 

[--[no|confirm]releaseLocks] [--hostname=server] [--port=number] 





DESCRIPTION 

si closecp closes a change package. 

Note: If reviews are mandatory, you cannot close the change package using this command. The 

change package can only be closed by Source Integrity once it has successfully completed the 

review process. For more information, see the Source Integrity Enterprise User Guide. 

Options 



--[no|confirm]allowOrphanedDeferred 

controls if orphaned deferred operations are permitted when the change package is closed. 

--[no]confirm 

controls whether to confirm closing individual change packages. 

--[no|confirm]releaseLocks 

controls whether or not outstanding locks are released when the change package is closed. 

issue... 


issue identifies a specific issue that contains all open change packages that you want to 

close; use spaces to specify more than one issue. 

issue:change package id identifies a specific change package to close; use spaces to 


DIAGNOSTICS 

65 of 457


PREFERENCES 



SEE ALSO 

Commands: 


viewcps 



66 of 457

si co 

checks out members into working files in a sandbox 

SYNOPSIS 

si co [--mergeType=[confirm|cancel|automatic|manual]] 

[--onMergeConflict=[confirm|cancel|mark|launchtool|highlight|error]] [--[no]branch] 

[--[no|confirm]branchVariant] [(--cpid ID|--changePackageId=ID)] [ --issueId=ID] 

[(-l|--[no]lock)] [--[no|confirm]lockOnFreeze] [--[no|confirm]merge] 

[--onLock=[confirm|branch|makewritable|branchconfirm|makewritableconfirm|cancel] ] 

[(-r rev|--revision=rev)] [(-u|--unlock)] [--[no]update] [--[no|un]expand] [-f] 

[--[no|confirm]overwriteChanged] [--[no|confirm]overwriteDeferred] 

[--[no]restoreTimestamp] [(-R|--[no|confirm]recurse)] [--filter=filteroptions] 

[(-S sandbox|--sandbox=sandbox)] [--hostname=server] [--port=number] [--password=password] 



[--settingsUI=[gui|default]] [--status=[none|gui|default]] sandbox member... 

DESCRIPTION 

si co checks out members, typically for modification. If no members are specified, si co applies to all 

sandbox members. 

Check out is an operation that extracts the contents of a revision in an archive and copies it to a working file. 

You can check out any revision by specifying either its revision number or label. By default, the member 

revision is used. If an existing revision other than the head revision is specified, a branch from that revision is 

created. 

Use the si resync command to just get a read-only copy of a member. 

Options 

This command takes the universal options available to all si commands, as well as some general options. 

See the options reference page for descriptions. 

--mergeType=[confirm|cancel|automatic|manual] 

specifies how you want merge changes from the working file in your sandbox into the working file that 

will be created upon check out. 

--mergeType=confirm prompts you to confirm a merge type. 

--mergeType=cancel cancels the selected merge. 

--mergeType=automatic completes the merge process without launching the MKS Visual Merge tool. 

Warning: While Source Integrity and MKS Visual Merge are capable of performing automatic merging, 

67 of 457

MKS cannot guarantee that the merged results are “correct”. MKS recommends that you examine and 

test the merged results before checking them into the repository. 

--mergeType=manual completes the merge operation through the MKS Visual Merge tool. The MKS 

Visual Merge tool launches, displaying the revisions you want to merge. For more information on the 

MKS Visual Merge tool, refer to the Source Integrity Enterprise User Guide. 

--onMergeConflict =[confirm|cancel|mark|launchtool|highlight|error] 

specifies what to do when conflicts occur during a merge. 

--onMergeConflict=confirm prompts you to confirm a merge conflict option. 

--onMergeConflict=cancel cancels the merge. 

--onMergeConflict=mark marks the revisions indicating that merging is required without 

completing all of the merge related tasks. This provides time you may need to investigate conflicts or 

consult on editing or difference blocks before finishing the merge. 

--onMergeConflict=launchtool launches the MKS Visual Merge tool to resolve the conflicts, all nonconflicting 

blocks will already have been applied. 

--onMergeConflict=highlight indicates conflicts in the file with the following characters: "". 

--onMergeConflict=error indicates merge conflicts with an error message prompt. 

Note: --onMergeConflict=launchtool does not require the -g or --gui options. 

--[no]branch 

controls whether to force the creation of a branch revision. Specifying --branch always creates a 

branch. 

For details on branch revisions, see the si ci reference page. 

--[no|confirm]branchVariant 

controls whether Source Integrity should create a branch off of the revision you are checking out, if you 

are working in a variant sandbox. This reduces the possibility of locking conflicts with the member while 

work is being done in the variant and regular sandboxes. Specifying --confirmbranchVariant 

causes a prompt to be displayed so you can confirm the branching. 

This option overrides the branchIfVariant preference that you can set with the si setprefs 


This option is useful because development paths can conflict when developers working on different 

paths need to work on the same revision of a file. There is also the potential to conflict when 

development paths access the same member histories. For example, suppose the current version of a 

project includes utility.dll, version 1.4 and the variant sandbox contains utility.dll, version 

1.3. Both versions are stored in the same member history, and therefore a conflict is possible. Using 

the --branchVariant option helps handle such conflicts. 

68 of 457

For details on development paths and variant sandboxes, see the si createsandbox reference 

page. 

--cpid=ID 


identifies a change package that is notified of this action, for example, 1452. Note the following about 

using this option: 


❍ You must specify this option if you have requested to obtain a lock and TrackLocks is enabled, 

and/or it is mandatory to specify a change package. 

❍ If it is not mandatory to specify a change package, or if no change package is applicable, you 

must specify --changePackageId=:none. 

❍ The next time you are prompted for a change package ID, the last used change package ID is 

displayed by default, if :none was specified or at least one change package was successfully 

updated from the last operation. 

--issueId=ID 

identifies an MKS Integrity Manager issue that is notified of this action. This option is another way of 

adding members to a change package. If you have an issue assigned to you that contains one open 

change package, you can specify the issue ID instead of the change package ID. See the Integrity 

Server Administration Guide or your administrator for details on using the Integrity Manager integration. 

-l 

--[no]lock 

controls whether to create locks on members. 

--[no|confirm]lockOnFreeze 

controls whether to lock the specified member even if it is frozen. 

--lockOnFreeze means always do it. 

--nolockOnFreeze means never do it. 

--confirmlockOnFreeze means always ask before doing it. 

--[no|confirm]merge 

controls whether to merge changes from the working file in your sandbox into the working file that will 

be created upon check out. 

--merge means always do it. 

--nomerge means never do it. 

--confirmmerge means always ask before doing it. 

Note: By default, Source Integrity prompts you for the type of merge (manual or automatic) to perform 

and what action to take if a conflict is encountered. 

--onLock=[confirm|branch|makewritable|branchconfirm|makewritableconfirm|cancel] 

controls whether to make the working file writable, create a branch, or cancel the operation. 

--onLock=confirm means always ask whether to make the working file writable, create a branch, or 

cancel the operation. 

69 of 457

--onLock=branch means create a branch. 

--onLock=makewritable means make the working file writable. 

--onLock=branchconfirm means always ask before creating a branch. 

--onLock=makewritableconfirm means always ask before making the working file writable. 

--onLock=cancel means cancel the operation. 

-u 

--unlock 

keeps the member unlocked, and is equivalent to --nolock. 

--[no]update 

controls whether to update the project's member revision to the checked out revision. 

Note: In a variant sandbox, specifying si co --noupdate --branchVariant member updates 

the member revision. 


controls whether to expand, unexpand, or ignore keywords in the member file. Keyword expansion is 

only available in text archives, not binary archives. For descriptions of the MKS Source Integrity 

keywords, see the Source Integrity Enterprise User Guide. Possible keywords are: 

$Author$ 

$CompanyInfo$ 

$Date$ 

$Header$ 

$Id$ 

$Locker$ 

$Log$ 

$Name$ 

$ProjectName$ 



$RCSfile$ 

$Revision$ 



$Source$ 

$State$ 

-f 

overwrites the working file if it has changed since it was last checked in. This is equivalent to specifying 

--overwriteChanged. 

--[no|confirm]overwriteChanged 

controls whether to overwrite the working file if it has changed since it was last checked in. 

--overwriteChanged means always do it 

70 of 457

--nooverwriteChanged means never do it 

--confirmoverwriteChanged means always ask before doing it. Specifying the --yes or --no 

options would have the same effect as the first two, but would further answer "yes" or "no" to all 

questions asked, not just this one. 

--[no|confirm]overwriteDeferred 

controls whether to overwrite the working file if there is a deferred operation on the member. 

--[no]restoreTimestamp 

controls whether to restore the timestamp of the working file to the timestamp of the revision in the 

member history. If this is not specified, the timestamp is set to the current date and time. 



DIAGNOSTICS 


PREFERENCES 


SEE ALSO 

Commands: 

si ci, si closecp, si cpissues, si createcp, si diff, si edit, si lock, si resync, 

si rlog, si unlock, si viewcps 



71 of 457

si configuresandbox 

configures sandbox properties 

SYNOPSIS 

si configuresandbox [--lineTerminator=[lf|crlf|native]] [--[no]shared] 

[--[no]sparse] [--hostname=server] [--port=number] [--password=password] 



[--settingsUI=[gui|default]] [--status=[none|gui|default]] sandbox location... 

DESCRIPTION 

Source Integrity provides a way to configure the following sandbox properties: sandbox sharing, 

line terminator and sparse settings. 

Options 



---lineTerminator=[lf|crlf|native] 

explicitly identifies the characters to use as the line terminator for this sandbox. lf is a line 

feed character, crlf is the combination of the carriage return and line feed characters, and 

native uses the default line terminator in the client operating system: crlf in Windows and lf 

in UNIX. 

Note: 

When you create a sandbox Source Integrity remembers the setting of the line 

terminator, and all checkouts (using si co) and resyncs (using si resync) in that 

sandbox use the same line terminator setting. If you want to override the line 

terminator on an individual member, you must use some utility such as the MKS 

Toolkit flip command. 

--[no]shared 

controls whether or not to make the sandbox shared. 

Configuring the sandbox to be shared makes it possible for other users to share its working 

files. Other users must first import the sandbox to register it with their Source Integrity clients 

(see si importsandbox). When a top-level sandbox is configured to be shared, all 

subsandboxes are shared as well. Subsandboxes cannot be individually configured to be 

shared or not shared. 

72 of 457

When sandbox sharing is removed, users sharing the sandbox each receive an error 

message stating the change in sharing configuration the next time they attempt to access 

the sandbox or perform an operation on its contents. 

--[no]sparse 

controls whether or not to make the sandbox sparse. 

Making the sandbox sparse with --sparse affects the way the sandbox behaves with the 

si ci check in command and the si co check out command, as well as si resync . 

The intent of a sparse sandbox is that it contains only those working files that are actively 

being worked on by you at the time. Using si ci to check in a member to a sparse 

sandbox removes the working file from the sandbox (unless you did a check in locked, using 

the -l option). Similarly, using si resync on the sandbox will by default remove the 

working files for those members which are not locked by you, although you can override this 

with si resync --populate in a sparse sandbox, which in effect causes the resync to 

behave like it does in a "normal", non-sparse sandbox. 

sandbox location... 

specifies the path of the sandbox directory including the project file. For example, 

C:\sourcecode\framework\scripts\project.pj. 

DIAGNOSTICS 


PREFERENCES 



SEE ALSO 

Commands: 

si createsandbox, si importsandbox 



73 of 457

si configuresubproject 

configures a subproject's type 

SYNOPSIS 

si configuresubproject [-r subproject revision|--subprojectRevision=subproject revision] 


name] [--type=[normal|variant|build|reset]] [(-P project|--project=project)] 

[(-S sandbox|--sandbox=sandbox)] [--devpath=path] [--hostname=server] [--port=number] 

[--password=password] [--user=name] [(-?|--usage)] [(-F file|--selectionFile=file)] [(-N|--no)] 

[(-Y|--yes)] [--[no]batch] [--cwd=directory] [--forceConfirm=[yes|no]] [(-g|--gui)] [--quiet] 

[--settingsUI=[gui|default]] [--status=[none|gui|default]] subproject or subsandbox 

DESCRIPTION 

Once you have created or added a subproject, you can modify the type to suit your needs. For example, you can 

change a normal subproject to a build subproject to suspend development, or you can change a variant subproject to 

a normal subproject to continue development on the main trunk. 

Important: Any changes you make when reconfiguring a subproject affects the project as a whole and any shared 

subprojects. More specifically, changing the type, revision, or development path of a subproject can radically change 

the list of members of that subproject. After configuring a subproject, existing sandboxes whose contents were in 

sync with the subproject before it was configured will display deltas when you use si viewproject and si 

viewsandbox, reflecting the following possible differences: 

● Members that exist in both the old and new version of the subproject display a delta if the working revision in 

the sandbox is different from the new member revision. 

● Members that are in the new version of the subproject but were not in the old version of the subproject display 

a "no working file" delta, indicating that the sandbox does not have a copy of the new member yet. 

● Members that were in the old version of the subproject but are not in the new version display as former 

members. 

● Subprojects that were in the old version of the subproject but are not in the new version will display as former 

subprojects. 

Options 



-r=subproject revision 







--type=[normal|variant|build|reset] 


74 of 457

--type=normal configures the subproject to the master (non-variant) version of the subproject. 












specifies the path and name of the project where the subproject exists, for example, 


subproject 

subsandbox 

specifies the subproject or subsandbox name to which the new configuration applies, for example, tools.pj 

PREFERENCES 


SEE ALSO 

Commands: 

si addsubproject, si checkpoint, si createproject, si createsandbox, si 

createsubproject, si drop, si dropproject, si importproject, si projectinfo, si 

projects, si sharesubproject, si viewproject 



75 of 457

si connect 

establishes a connection to an Integrity Server 

SYNOPSIS 

si connect [--hostname=server] [--port=number] [--password=password] [--user=name] 




DESCRIPTION 

si connect establishes a connection to an Integrity Server host. Most commands implicitly 

connect to the host, this does so explicitly. In fact, all the other commands call si connect to 

establish the connection. The client supports multiple connections to multiple servers. You can use 

si disconnect to disconnect from an Integrity Server host. 

Options 



--hostname=server 

identifies the name of the host server where the Integrity Server is located. 

--password=password 

identifies the password to use for connecting to the Integrity Server. 

--port=number 

identifies the port on the host server where the Integrity Server is located. 

--user=name 

identifies the user to use for connecting to the Integrity Server. This typically defaults to the 

name you have used to log into your client machine. 

DIAGNOSTICS 


PREFERENCES 



76 of 457

SEE ALSO 

Commands: 

si disconnect, si exit, si servers 



77 of 457

si cpissues 

displays all Integrity Manager issues that are in a valid state to accept new change 

packages 

SYNOPSIS 

si cpissues [--fields=field1[:width1],field2[:width2]...] [--hostname=server] 



[--forceConfirm=[yes|no]] [--[no]persist] [--quiet] 

DESCRIPTION 

si cpissues displays all Integrity Manager issues that are in a valid state to accept new change 

packages. Only issues assigned to the user are displayed. 

Options 




allows you to select fields to be printed, specified in the format 

field1[:width1],field2[:width2].... Specifying the column [:width] (in pixels) for each field is 

optional - widths are only available with the -g or --gui options. Under the CLI the fields 

are separated with a space. 


id 

displays issue IDs. 

summary 

displays issue summaries. 

--[no]persist 

controls the persistence of CLI views. 

DIAGNOSTICS 


78 of 457

PREFERENCES 



SEE ALSO 

Commands: 

si add, si ci, si co, si createcp , si createcp, si drop, si lock, si 

viewcps 



79 of 457

si createcp 

creates a new change package 

SYNOPSIS 

si createcp [--description=value] [--issueId=value] [--summary=value] 





DESCRIPTION 

si createcp creates a new change package. 

Options 



--description=value 

specifies a description of the change package being created. 

--issueId=value 

specifies the ID of the issue you are creating a change package for. This option can only be 

specified if the integration between Source Integrity and Integrity Manager is enabled. 

Important: Your ability to create a change package is based on the change package 

creation policy for the type that you want to create a change package for. 

--summary=value 

specifies a brief summary of the change package being created. 

Note: A change package summary is mandatory. 

DIAGNOSTICS 


PREFERENCES 

80 of 457



SEE ALSO 

Commands: 

si add, si ci, si co, si cpissues, si drop, si lock, si viewcps 



81 of 457

si createdevpath 

creates a development path 

SYNOPSIS 

si createdevpath [--projectRevision=rev] [--devpath=path] 

[(-P project|--project=project)] [(-S sandbox|--sandbox=sandbox)] [--hostname=server] 





DESCRIPTION 

si createdevpath creates a development path for specific project revisions, effectively creating a 

variant project. 

Regular sandboxes are based upon the current state of the project. You can also create a sandbox 

that is based upon a previously checkpointed revision of the project. This type of sandbox is called 

a variant. When you create a variant sandbox, using the si createsandbox command, you 

choose a checkpoint (snapshot) of your project and use it as a starting point for new development. 

MKS Source Integrity allows you to do this by defining a new development path. 

A development path is an identifier given to a new direction of software development. Changes 

made through the development path are kept separate from the main development trunk unless 

you choose to merge them into it later. 

Source Integrity allows multiple developers to point to the same development path, each using 

their own variant sandbox. In the variant sandbox, you can see the current state of the project 

along the development path and the changes made by other developers using it. 

When a variant project is created, it is also created for all subprojects, reserving the assigned 

name as a unique identifier and ensuring no two paths can share the same name. 

Development paths are useful for performing post-release maintenance. Variant sandboxes 

pointing to a post-release development path allow you to make changes to a previous revision of a 

project. Any fixes, patches, or changes you check in go onto a branch and do not affect the main 

project, unless you choose to merge them. 

Note: 

You may instead create branch revisions in the main project, rather than creating a variant 

82 of 457

Options 

sandbox through a new development path, by specifying --branch when checking files out 

or in. You still may have to merge changes, but the development path remains the same. 

For details on simply branching revisions, see the si ci reference page. 



--devpath=path 

identifies the name of the new development path. 

Note: The following characters may not be used in a development path: \n, \r, \t, :, [', '], #. 

--projectRevision=rev 

identifies the checkpointed revision number to create the variant against. 

DIAGNOSTICS 


PREFERENCES 



SEE ALSO 

Commands: 

si archiveinfo, si createsandbox, si dropdevpath, si memberinfo, si 

projectinfo, si revisioninfo, si rlog 



83 of 457

si createproject 

creates a new empty project 

SYNOPSIS 

si createproject [--[no]openView] [--hostname=server] [--port=number] 




project location 

DESCRIPTION 

si createproject creates a new, empty project on the Integrity Server in a specified directory. 

Options 




controls whether to open the project view after this new project is registered on the server. If 

--noopenView is used, the project view does not open. 

project location 

identifies a location on the Integrity Server for the new project. Regardless of your operating 

system, all paths are specified here using forward slashes (/), and are server absolute 

paths. You must also specify the name of the project file as part of the location; typically this 

is project.pj. 

Note: 

By convention, you should name your new project file with a suffix of .pj. 

Intermediate directories on the Integrity Server are created for you. Remember, however, 

that server-side restrictions may exist controlling where you are permitted to locate any 

projects. Contact your system administrator for permitted locations. 

DIAGNOSTICS 


84 of 457

PREFERENCES 



SEE ALSO 

Commands: 

si checkpoint, si createsandbox, si createsubproject, si dropproject, si 

importproject, si projects, si viewproject 



85 of 457

si createsandbox 

creates a new sandbox on your local machine 

SYNOPSIS 

si createsandbox [(-R|--[no|confirm]recurse)] [--lineTerminator=[lf|crlf|native]] 

[--[no]populate] [--[no]sparse] [--[no]openView] [--[no]shared] 

[(-Pproject|--project=project)] [--devpath=path] [--projectRevision=rev] 




[--settingsUI=[gui|default]] [--status=[none|gui|default]] [--xmlapi] directory 

DESCRIPTION 

si createsandbox creates a new sandbox on the client machine in a specified directory. When 

creating a sandbox you are able to determine the type of sandbox you want it to be: 

● The default regular type creates a sandbox based upon the current state of the project. 

● Choosing to create a variant creates a sandbox based upon a specific revision of the 

master project and is used for branching off the main development path. You first have to 

specify a development path other than the default one; to create a development path, see 

the si createdevpath command. 

● You may also choose to create a build sandbox. A build sandbox creates a static sandbox 

based upon a specific revision of the master project that is used for building or testing the 

project, but not for further development. 

Variant Sandboxes and Development Paths 

By default, si createsandbox creates regular sandboxes that are based upon the current state 

of the project. You can also create a variant sandbox, a sandbox that is based upon a previously 

checkpointed revision of the project. When you create a variant sandbox, you choose a checkpoint 

(snapshot) of your project and use it as a starting point for new development. MKS Source Integrity 

allows you to do this by defining a new development path and then specifying that path with the 

--devpath option. For example: 

si createsandbox --devpath=MyVariant 

A development path is an identifier given to a new direction of software development. Changes 

made through the development path are kept separate from the main development trunk unless 

you choose to merge them (see si merge) into it later. Source Integrity allows multiple 

developers to point to the same development path, each using their own variant sandbox. In the 

86 of 457

variant sandbox, you can see the current state of the project along the development path and the 

changes made by other developers using it. 

When a variant sandbox is created for the first time, it is also created for all subprojects, reserving 

the assigned name as a unique identifier and ensuring no two paths can share the same name. 

Development paths are useful for performing post-release maintenance. Variant sandboxes 

pointing to a post-release development path allow you to make changes to a previous revision of a 

project. Any fixes, patches, or changes you check in go onto a branch and do not affect the main 

project, unless you choose to merge them. 

Build Sandboxes 

After major milestones, such as product releases, you might want to recreate a static version of an 

entire project as it existed at some point in the past. You create a build sandbox, to build or test the 

project, not to begin further work along a new development path. 

A build sandbox is associated with a particular project revision, and has no development path 

(since it is static and not meant for further development). For example: 

si createsandbox --projectRevision=1.34 

creates a build sandbox based on the project revision 1.34, and it cannot be modified. 

With a build sandbox, you cannot: 

● check out, lock, or check in members 

● remove or add members 

● freeze or thaw members 

● checkpoint the master project 

● modify project or member attributes 

● revert members 

● set the member revision 

However, with a build sandbox, you can: 

● change labels and states (see si addlabel) 

● resynchronize your sandbox (see si resync) 

● compare a member revision in the build sandbox to another revision (see si diff) 

● merge a member revision (si merge) in the build sandbox with another revision (of course, 

you cannot check that merged file back into the build sandbox) 

● check for differences between project revisions, such as changes to a project since it was 

last checkpointed (see si mods) 

87 of 457

Options 



--lineTerminator=[lf|crlf|native] 

explicitly identifies the characters to use as the line terminator for this sandbox. lf is a line 

feed character, crlf is the combination of the carriage return and line feed characters, and 

native uses the default line terminator in the client operating system: crlf in Windows and lf 

in UNIX. 

Note: 

When you create a sandbox Source Integrity remembers the setting of the line 

terminator, and all checkouts (using si co) and resyncs (using si resync) in that 

sandbox use the same line terminator setting. If you want to override the line 

terminator on an individual member, you must use some utility such as the MKS 

Toolkit flip command. 

--[no]populate 

controls whether to populate the sandbox with read-only working files for all members. 

--[no]sparse 

controls whether to create a sparse sandbox. 

Creating a sparse sandbox with --sparse affects the way the sandbox behaves with the 

si ci check in command and the si co check out command, as well as si resync. This 

option creates a sandbox with no working files and defers the creation of sandbox 

directories and subsandboxes until you need to work with them. A sparse sandbox does not 

retain working files when a member is checked in and continues to function this way 

throughout its use; however, once created, sandbox directories and subsandboxes remain 

in the sandbox. Using si ci to check in a member to a sparse sandbox removes the 

working file from the sandbox (unless you did a check in locked, using the -l option). 

Similarly, using si resync on the sandbox by default removes the working files for those 

members that are not locked by you, although you can override this with 

si resync --populate in a sparse sandbox, which in effect causes the resync to behave 

like it does in a normal, non-sparse sandbox. 


controls whether to open the sandbox view after this new sandbox is registered on the 

client. If --noopenView is used, the sandbox view does not open. 

--[no]shared 

controls whether or not to make the sandbox shared. The default is not shared. 

Configuring the sandbox to be shared makes it possible for other users to share its working 

files. Other users must first import the sandbox to register it with their Source Integrity clients 

(see si importsandbox). When a top-level sandbox is configured to be shared, all 

88 of 457

subsandboxes are shared as well. Subsandboxes cannot be individually configured to be 

shared or not shared. 

directory 

identifies a location on the MKS Source Integrity client system for the new sandbox. Use 

spaces to identify more than one directory. 

Note: 

DIAGNOSTICS 

Do NOT append the name of the project file (typically project.pj) to the directory. 

The name will be calculated automatically. 


PREFERENCES 



SEE ALSO 

Commands: 

si add, si checkpoint, si co, si createdevpath, si createproject, si 

dropsandbox, si importsandbox, si merge, si resync, si sandboxes, si 

viewsandbox 



89 of 457

si createsubproject 

creates a subproject or adds an existing project as a subproject 

SYNOPSIS 

si createsubproject [ --[no|confirm]reuseDroppedSubproject] 

[ --[no]createSubprojects] [(-P project| --project=project)] 

[(-S sandbox| --sandbox=sandbox)] [--devpath=path] [--hostname=server] 

[--port =number] [--password=password] [ --user=name] [(-?|--usage)] 

[(-F file|--selectionFile=file)] [(-N|--no)] [(-Y|--yes )] [--[no]batch] [ --cwd=directory] 

[--forceConfirm=[yes|no]] [(-g|--gui)] [ --quiet] [--settingsUI=[gui|default]] 

[ --status=[none|gui|default]] subproject location... 

DESCRIPTION 

si createsubproject creates a subproject on the server in a specified directory, which must 

be under an existing project specified by the -P project or --project=project options. This 

command works with Regular and Variant sandboxes, but not with Build sandboxes. 

Options 



--[no|confirm]reuseDroppedSubproject 

controls whether to add an existing subproject to the named project. This can be useful if the 

existing subproject had been dropped from a project. 

Note: While si addsubproject is the recommended command for adding an existing 

subproject to a project, this option is available for backwards compatibility and any scripts 

you may use. 


controls whether to create one subproject for each directory encountered when creating 

subprojects. 

subproject location... 

identifies a location on the Integrity Server for the new subproject. Regardless of your 

operating system, all paths are specified here using forward slashes (/), and may be server 

relative or absolute paths. You must also specify the name of the project file as part of the 

location; typically this is project.pj. 

Note: 

Subprojects must be added "in tree", that is, in the project directory or a subdirectory. 

90 of 457

As with the si createproject command, remember that server-side restrictions may 

exist controlling where you are permitted to locate any subprojects on the Integrity Server. 

Contact your system administrator for permitted locations. 

DIAGNOSTICS 


PREFERENCES 



SEE ALSO 

Commands: 

si checkpoint, si createproject, si createsandbox, si drop, si 

dropproject, si importproject, si projectinfo, si projects, si 

viewproject 



91 of 457

si deletelabel 

removes a label from a member 

SYNOPSIS 

si deletelabel [(-L label|--label=label)] [--filter=filteroptions] 



[--user=name] [(-?|--usage)] [(-F file|--selectionFile=file)] 

[-R|--[no|confirm]recurse] [(-N|--no)] [(-Y|--yes)] [--[no]batch] [--cwd=directory] 



DESCRIPTION 

si deletelabel removes a label from one or more members. If you do not specify any 

members, the si deletelabel command applies to all project members with associated 

archives, deleting the label from whatever revision the label happens to exist on in the archive. 

Please note the --projectRevision option is not used for identifying the revision to delete 

labels from. 

Options 



-L label 

--label=label 

identifies a label. Labels cannot contain colons(:), square brackets ([ ]), or leading spaces. 

Additionally, they cannot have the same format as a valid revision number. 

Note: 

Labels that include spaces must be enclosed by quotes. 

member... 


DIAGNOSTICS 


92 of 457

PREFERENCES 



SEE ALSO 

Commands: 

si addlabel, si addprojectlabel, si deleteprojectlabel , si viewlabels 



93 of 457

si deleteprojectlabel 

removes a label from a project 

SYNOPSIS 

si deleteprojectlabel [(-L label|--label=label)] [(-P project|--project=project)] 






DESCRIPTION 

si deleteprojectlabel removes a label from an MKS Source Integrity project, deleting the 

label from whatever project revision the label happens to exist on. Note that the 

--projectRevision option is not used for identifying the project revision to delete labels from; it 

is the generic option available on all project-based commands that allows you to specify the 

revision of the build project you want to work with. 

Options 



-L label 

--label=label 

identifies a label. Labels cannot contain colons(:), square brackets ([ ]), or leading spaces. 

Additionally, they cannot have the same format as a valid revision number. 

Note: 

Labels that include spaces must be enclosed by quotes. 

DIAGNOSTICS 


PREFERENCES 



94 of 457

SEE ALSO 

Commands: 

si addlabel, si addprojectlabel, si deletelabel, si viewlabels 



95 of 457

si deleterevision 

permanently deletes a revision from a member 

SYNOPSIS 

si deleterevision [--[no]confirm] [--[no]confirminuse] [-f] [--range=value] 







DESCRIPTION 

si deleterevision deletes an archived revision of a project member. 

Note: 

Options 

It is recommended that you never delete a revision. Since historical versions of projects may 

still point at the deleted revision, it may become impossible to recreate old projects. 



--[no]confirm 

controls the display of confirmation messages. 

--[no]confirminuse 

controls whether Source Integrity warns you about deleting the revision if it is used in other 

projects. If the revision is used in other projects, Source Integrity warns you that deleting the 

selected revision will break the listed items. This option is valid only with the database 

repository. 

-f 

forces the revision to be deleted, without any confirmation message. 

--range=value 

specifies a range of revision numbers. The format of value for a single revision is simply the 

revision number itself. Separate multiple non sequential revisions with a comma, and use a 

dash to indicate a sequential range, for example, 1.2-1.5. 

You may also prefix or append a dash to a single revision number, meaning you want to 

96 of 457

delete from 1.1 to the specified revision, or from the specified revision to the tip. For 

example, you would specify -1.6 to delete revisions 1.1 to 1.6. Or you could specify 1.2- 

to delete revisions 1.2 to the tip revision, whatever it may be. 

The revisions are deleted in order from the highest revision to the lowest. 

member... 


DIAGNOSTICS 


PREFERENCES 



SEE ALSO 

Commands: 

si diff, si merge, si revisioninfo, si rlog 



97 of 457

si demote 

demotes the state of a member 

SYNOPSIS 

si demote [(-r rev|--revision=rev)] [(-s state|--state=state)] 

[(-R|--[no|confirm]recurse)] [--devpath=path] [--filter=filteroptions] 

[(-P project|--project=project)] [--projectRevision=rev] 


[--password=password] [--user=name] [--cwd=directory] [(-F file|--selectionFile=file)] 


[--settingsUI=[gui|default]] [--status=[none|gui|default]] [(-?|--usage)] [(-Y|--yes)] 

member... 

DESCRIPTION 

si demote demotes a project member to a lower state of development. A state is a textual 

description defined by the administrator to classify the condition of a revision in a history. If no state 

is assigned to a revision at check-in, a default value of Exp (for Experimental) is used. See the 

Integrity Server Administration Guide for details on setting up states. 

Project members can also be demoted to a predefined lower state of development using this 


Note: Demoting members is for historical purposes only. To more effectively control project 

workflow, MKS recommends using the Integrity Manager integration. 

Options 



-s state 

--state=state 

specifies the target state to be set for the demoted member. If a state is not specified, the 

member is demoted to the next state. 

member... 


DIAGNOSTICS 

98 of 457


PREFERENCES 



SEE ALSO 

Commands: 

si demoteproject, si promote, si promoteproject 



99 of 457

si demoteproject 

demotes the state of a project 

SYNOPSIS 

si demoteproject [(-s state|--state=state)] [(-P project|--project=project)] 






DESCRIPTION 

si demoteproject demotes a project to a lower state of development. A state is a textual 

description, defined by the administrator, used to classify the condition of a revision in a history. If 

no state is assigned to a revision at checkpoint, a default value of Exp (for Experimental) is used. 

See the Integrity Server Administration Guide for details on setting up states. 

Just as you can with a project member, you can demote the project itself (change its state, in other 

words). Only the project is demoted, not the members of the project. 

Note: Demoting projects is for historical purposes only. To more effectively control project 


Options 



-s state 

--state=state 

specifies the target state to be set for the demoted project. If no state is specified, the 

project is demoted to the next state. 

DIAGNOSTICS 


PREFERENCES 

100 of 457



SEE ALSO 

Commands: 

si demote, si promote, si promoteproject 



101 of 457

si diff 

displays differences between two revisions of a member 

SYNOPSIS 

si diff [--context=value] [--[no]ignoreBlanks] [--[no]ignoreCase] 

[--[no]ignoreWhitespace] [-r rev1[-r rev2]] [(-R|--[no|confirm]recurse)] 

[--filter=filteroptions] [(-P project|--project=project)] [(-S sandbox|--sandbox=sandbox)] 

[--devpath=path] [--projectRevision=rev] [--hostname=server] [--port=number] 



[(-g|--gui)] [--quiet] [--settingsUI=[gui|default]] [--status=[none|gui|default]] member... 

DESCRIPTION 

si diff displays the differences between two revisions of the specified member, or one revision 

and the member's working file. If no members are specified, si diff operates on all project 

members. 

By default, in a sandbox, this compares the member revision against the working file. 

In graphical mode where the -g or --gui option is used, this invokes the visual difference utility. 

Otherwise, the diff or diffb utilities are used depending on whether it is evaluating differences 

in a text or binary file. 

If used with -g or --gui, only one member can be differenced at a time, and the --context 

option is ignored. 

Options 



--context=value 

shows value number of lines of context, before and after each difference between two files. 

si diff marks lines removed from the "old" revision with -, marks lines added to the 

"new" revision with +, and marks lines changed in both files with !. 

--[no]ignoreBlanks 

controls whether to ignore blanks when comparing textual revisions. When 

--ignoreBlanks is used, all differences involving blanks are ignored except blanks at the 

start of a line. These are treated differently than blanks between other characters. The 

following pair would be considered different, for example, because of the leading blank: 

102 of 457

a b c def 

a b c def 

--[no]ignoreCase 

controls whether to ignore case when comparing revisions. 

--[no]ignoreWhitespace 

controls whether to ignore white space at the end of each line (except the newline) and treat 

all consecutive strings of white space elsewhere in a line as equivalent (effectively, reducing 

all strings of white space to a single space for the purpose of comparing lines). 

-r rev1[-r rev2] 

uses a specified revision. Specify this option twice to identify the two revisions to be 

compared; the first instance is the "old" revision, the second is the "new". If the second 

revision is not specified, the working file is assumed. Both revisions must be specified if 

operating against a project. rev can be a valid revision number or a label. If neither is 

specified, it defaults to member revision. 

member... 

identifies a specific project or sandbox member, depending on whether the -S sandbox 

option or the -P project option is specified. To specify more than one member, use spaces 

between them. 

DIAGNOSTICS 


PREFERENCES 



SEE ALSO 

Commands: 

diff, diffb, si ci, si merge, si mods, si revisioninfo, si rlog, si 

updaterevision, si viewrevision, vdiff32 



103 of 457

si difffiles 

compares the differences between two text files 

SYNOPSIS 

si difffiles [--context=value] [--[no]ignoreBlanks] [--[no]ignoreCase] 

[--[no]ignoreWhitespace] [(-?|--usage)] [(-F file|--selectionFile=file)] [(-N|--no)] 

[(-Y|--yes)] [--[no]batch] [--cwd=directory] [--forceConfirm=[yes|no]] [(-g|--gui)] 

[--quiet] [--settingsUI=[gui|default]] [--status=[none|gui|default]] file1 file2 

DESCRIPTION 

si difffiles compares the differences between two text files. This is useful when you want to 

compare the differences between two arbitrary text files (not members or revisions). 

In graphical mode where the -g or --gui option is used, this invokes a dialog box that allows you 

to browse for each file. The results appear in MKS Visual Difference. 

Note: The dialog box keeps track of the last 10 files in both fields. 

Options 



--context=value 

shows value number of lines of context, before and after each difference between two files. 

si difffiles marks lines removed from the first specified file with -, marks lines added 

to the second specified file with +, and marks lines changed in both files with !. 

--[no]ignoreBlanks 

controls whether to ignore blanks when comparing text files. When --ignoreBlanks is 

used, all differences involving blanks are ignored except blanks at the start of a line. These 

are treated differently than blanks between other characters. The following pair would be 

considered different, for example, because of the leading blank: 

a b c def 

a b c def 

--[no]ignoreCase 

controls whether to ignore case when comparing files. 

--[no]ignoreWhitespace 

104 of 457

controls whether to ignore white space at the end of each line (except the newline) and treat 

all consecutive strings of white space elsewhere in a line as equivalent (effectively, reducing 

all strings of white space to a single space for the purpose of comparing lines). 

file1 file2 

identifies the two files you want to compare. 

DIAGNOSTICS 


PREFERENCES 



SEE ALSO 

Commands: 

diff, diffb, si diff, si ci, si merge, si mods, si revisioninfo, si rlog, si 

updaterevision, si viewrevision, 



105 of 457

si discardcp 

discards a change package 

SYNOPSIS 

si discardcp [--[no]confirm] [--hostname=server] [--port=number] 





DESCRIPTION 

si discardcp discards a change package. 

Source Integrity provides a way to remove change packages from active use when they are not 

needed by discarding them. 

Change packages can only be discarded if they are in the Open or Rejected states. In order to 

discard a change package, that change package must be both created by you and not contain any 

committed entries. However, a change package administrator may discard a change package 

created by another user. 

When a change package is discarded, the following happens where applicable: 

● all uncommitted entries are removed from the change package 

● all deferred operations corresponding to deferred entries are reverted 

● all locks on members corresponding to lock entries are released 

● all pending operations corresponding to pending entries are reverted, and appear as 

discarded entries in the review log (to preserve the review history) 

● all pending revisions that correspond to pending entries are deleted 

● any archives created for pending members associated with pending entries in the change 

package are deleted from the server (pre-existing archives that were shared to create a 

pending member are not deleted) 

Note the following about discarded change packages: 

● The change package ID for the discarded change package can never be used for any future 

change packages that are created. 

● Discarded change packages have a state of Discarded, and can still be viewed using the 

Change Package filter. 

● If the change package has undergone a review, the review log persists. 

106 of 457

● Discarded change packages can be opened and used again. 

Options 



--[no]confirm 

specifies if to confirm discarding the change package. 

issue... 


issue identifies a specific issue that contains all change packages that you want to discard; 


issue:change package id identifies a specific change package to discard; use spaces to specify 

more than one change package. 

DIAGNOSTICS 


PREFERENCES 



SEE ALSO 

Commands: 


viewcps si acceptcp, si rejectcp, si opencp 



107 of 457

si disconnect 

disconnects from the Integrity Server 

SYNOPSIS 

si disconnect [--hostname=server] [--port=number] [--password=password] 


[--[no]batch] [--[no]confirm] [--cwd=directory] [--forceConfirm=[yes|no]] [(-g|--gui)] 

[--quiet] [--settingsUI=[gui|default]] [--status=[none|gui|default]] 

DESCRIPTION 

si disconnect disconnects the client connection to the host Integrity Server. 

Note: When disconnecting a connection that is the current connection, all open client views close. 

All new views use the connection specified in the Source Integrity preferences, or an existing 

connection, as the new current connection. 

Options 



--[no]confirm 

controls whether to implement the Integrity Server disconnection confirmation policy. 

DIAGNOSTICS 


PREFERENCES 



SEE ALSO 

Commands: 

si connect, si servers 

108 of 457



109 of 457

si drop 

drops a member or subproject from a project 

SYNOPSIS 

si drop [(--cpid ID|--changePackageId=ID)] [--[no|confirm]closeCP] 

[--issueId=ID] [(-f|--[no]confirm)] [--[no]defer] [--[no]delete] 


[--devpath=path] [--hostname=server] [--port=number] [--password=password] 



[--settingsUI=[gui|default]] [--status=[none|gui|default]] member... or subproject... 

DESCRIPTION 

si drop drops specified members and subprojects from a project. Files dropped in a sandbox are 

not actually dropped from the sandbox until you use the si resync command, or if you specify 

--delete with this command. This allows sandbox users to be protected from a file deletion until 

an appropriate point, and therefore be in control. 

Note: 

This command does not operate in a Build sandbox. 

If a member has outlived its usefulness or just does not belong in a project any more, you can 

remove it at any time. After you remove a member from a project, the member is no longer listed 

as part of the sandbox or master project, but the member history remains, in case you need to 

recreate an earlier version of the project. The build project and variants may still have the file as a 

member. 

Adding a member (see si add) which has previously been dropped will result in the history of the 

dropped member becoming the history of the newly added member. 

Options 



--cpid=ID 




110 of 457














--issueId=ID 




package ID. See the Integrity Server Administration Guide or your administrator for details 

on using the Integrity Manager integration. 

-f 

--[no]confirm 

controls the display of confirmation messages. -f forces an action without any prompt. 

--[no]defer 

controls whether to delay the drop operation in the project until the deferred operation is 


--[no]delete 

control whether the working file should be deleted immediately from your sandbox, when 

using -S or 

--sandbox. 

member... or subproject... 

identifies a specific member or subproject; use spaces to specify more than one. 

DIAGNOSTICS 


PREFERENCES 


111 of 457


SEE ALSO 

Commands: 

si add, si closecp, si cpissues, si createcp, si viewcps 



112 of 457

si dropdevpath 

drops a variant project from the master project 

SYNOPSIS 

si dropdevpath [--devpath=path] [(-P project|--project=project)] 





DESCRIPTION 

si dropdevpath drops a variant project. 

Options 




identifies the development path of a project to be dropped. 

Note: The following characters may not be used in a development path: \n, \r, \t, :, [', '], #. 

DIAGNOSTICS 


PREFERENCES 



SEE ALSO 

Commands: 

si createdevpath, si createproject, si dropproject, si projectinfo, si 

projects, si viewproject 

113 of 457



114 of 457

si dropmemberattr 

drops an attribute from a member 

SYNOPSIS 

si dropmemberattr [(--attr=key[=value]|--attribute=key[=value])] 







DESCRIPTION 

si dropmemberattr drops an attribute from a member. If no members are specified, the 

command applies to all members of the project. 

Options 





identifies the attribute key and, optionally, the value to be dropped. If only the key is given, 

this command deletes any attribute with that key. If a value is given for the key, then only a 

key with that value is dropped. 

member... 


DIAGNOSTICS 


PREFERENCES 



115 of 457

SEE ALSO 

Commands: 

si addmemberattr, si addprojectattr, si dropprojectattr 



116 of 457

si dropproject 

drops (unregisters) a project from an Integrity Server 

SYNOPSIS 

si dropproject [--hostname=server] [--port=number] [--password=password] 



[--settingsUI=[gui|default]] [--status=[none|gui|default]] project... 

DESCRIPTION 

si dropproject unregisters a project from the Integrity Server. Once a project is dropped, 

project commands do not operate on the project, and any sandboxes pointing to that project do not 

operate. 

Note: 

This works only on "top level" projects; to drop a subproject from its master project, use si 

drop . 

Options 



project... 

identifies a specific project location with a fully qualified server-relative path; use spaces to 

specify more than one. 

DIAGNOSTICS 


PREFERENCES 



SEE ALSO 

117 of 457

Commands: 

si createproject, si createsubproject, si drop, si importproject, si 

projects, si viewproject 



118 of 457

si dropprojectattr 

drops an attribute from a project 

SYNOPSIS 

si dropprojectattr [(--attr=key[=value]|--attribute =key[=value])] [(-P project|--project=project)] 

[(-S sandbox|--sandbox=sandbox)] [--devpath=path] [--hostname=server] [--port=number] [-password=password] 

[--user=name] [(-?|--usage)] [(-F file|--selectionFile=file)] [(-N|--no)] [(-Y|--yes)] [-- 

[no]batch] [--cwd=directory] [--forceConfirm=[yes|no]] [(-g|--gui)] [--quiet] [--settingsUI=[gui|default]] [-status=[none|gui|default]] 

DESCRIPTION 

si dropprojectattr drops an attribute from a project. 

Options 

This command takes the universal options available to all si commands, as well as some general options. See the options 

reference page for descriptions. 



identifies the attribute key and, optionally, the value to be dropped. If only the key is given, this command deletes any 

attribute with that key. If a value is given for the key, then only a key with that value is dropped. 

DIAGNOSTICS 


PREFERENCES 


SEE ALSO 

Commands: 

si addmemberattr, si addprojectattr, si dropmemberattr, si dropsandboxattr, si addsandboxattr 



119 of 457

si dropsandbox 

drops a sandbox 

SYNOPSIS 

si dropsandbox [--[no]confirm] [--delete=[none|members|all]] [-f] [(-?|--usage)] 



[--status=[none|gui|default]] sandbox location... 

DESCRIPTION 

si dropsandbox unregisters a sandbox from the Integrity Client. Once a sandbox is dropped, 

sandbox commands do not operate on the sandbox. 

Options 



-f 

--[no]confirm 

controls the display of confirmation messages. -f forces an action without any prompt. 

--delete=[none|members|all] 

deletes files from the client sandbox directory according to the value specified. If none is 

specified, then no deletion occurs after the sandbox is dropped. If members is specified, 

then the specified sandbox, subsandboxes, and members are deleted. If all is specified, 

then everything in the current directory and subdirectories is deleted. For example: 

--delete=none sandbox.pj 

causes sandbox.pj to be removed from the registry, but not deleted from the client directory. 

--delete=members sandbox.pj 

causes sandbox.pj to be removed from the registry and deleted from the client directory 

along with all its subsandboxes and members. 

120 of 457

Note: 

--delete=all sandbox.pj 

causes sandbox.pj to be removed from the registry and all files in the client directory and 

subdirectories to be deleted. 

Since --delete=all is a destructive operation, it always requires confirmation. This is a 

preventative security measure. For example, if you create a sandbox in the root of a file 

system, this operation would delete your entire drive. 

sandbox location... 

identifies the location of a specific sandbox; use spaces to specify more than one sandbox. 

DIAGNOSTICS 


PREFERENCES 



SEE ALSO 

Commands: 

si createsandbox, si importsandbox, si sandboxes, si viewsandbox 



121 of 457

si dropsandboxattr 

drops sandbox attributes 

SYNOPSIS 

si dropsandboxattr [--attr|attribute=key=value] [-S|--sandbox=value] 





DESCRIPTION 

si dropsandboxattr drops sandbox attributes. 

Options 





specifies the attribute to drop. 

DIAGNOSTICS 


PREFERENCES 



SEE ALSO 

Commands: 

si addsandboxattr, si configuresandbox, add projectattr, 

dropprojectattr 

122 of 457



123 of 457

si edit 

opens a revision or working file for editing 

SYNOPSIS 

si edit [--editor=value] [(-r rev|--revision=rev)] [--[no]systemEditor] [--filter=filteroptions] [(-P 

project|--project=project)] [(-S sandbox|--sandbox=sandbox)] [--devpath=path] [--projectRevision=rev] [-hostname=server] 

[--port=number] [--password=password] [--user=name] [(-?|--usage)] [(-F file|-selectionFile=file)] 

[(-N|--no)] [(-Y|--yes)] [--[no]batch] [--cwd=directory] [--forceConfirm=[yes|no]] [(-g|- 

-gui)] [--quiet] [--settingsUI=[gui|default]] [--status=[none|gui|default]] member... 

DESCRIPTION 

si edit opens a current, former, or deferred member revision for editing. In a sandbox, by default specifying no -r 

option edits the working file. 

If this command is invoked in the CLI mode (that is, no -g or --gui option is used), then the EDITOR environment 

variable is used and runs with the name of the temporary file containing the requested revision. If the EDITOR variable is 

not set, or if the -g or --gui option is used, a system-specific method is used. In particular, on WIN32-based systems, 

the operating system is instructed to open the file and does so based on the extension association. Under UNIX, the -g 

or --gui option uses the EDITOR environment variable; if it is not set, then Vi is used. 

Options 



--editor=value 

identifies the editor to be used, overriding any EDITOR environment variables or system setting. 

--[no]systemEditor 

controls whether to use the system editor, set through si setprefs. If set, this overrides any editor setting if -g or -gui 

is given. This is used to temporarily override the pereference system. 

member... 


DIAGNOSTICS 


PREFERENCES 


SEE ALSO 

Commands: 

si ci, si co, si lock, si unlock , si viewrevision 



124 of 457

si editcp 

edits an existing change package 

SYNOPSIS 

si editcp [--description=value] [--descriptionFile=value] 

[--state=[open|closed|submitted|accepted|rejected|discarded|commitfailed]] 

[--summary=value] [--summary=value] [--hostname=server] [--port=number] 



[--quiet] [(-g|--gui)] [--settingsUI=[gui|default]] issue|issue:change package id... 

DESCRIPTION 

si editcp edits an existing change package. 

Options 



--description=value 

specifies a description of the change package being edited. 

--descriptionFile=value 

specifies the file that contains the description for the change package. 

--state=[open|closed|submitted|accepted|rejected|discarded|commitfailed] 

specifies the state of the change package. The change package progresses through states 

as part of the change package review workflow. If reviews are not mandatory, some states 

are not applicable. For more information, see the Source Integrity Enterprise User Guide 

--state=[open] specifies that the change package is open. 

--state=[closed] specifies that the change package is closed. 

--state=[submitted] specifies that the change package has been submitted for review. 

--state=[accepted] specifies that the change package has been accepted by all 

reviewers. 

--state=[rejected] specifies that the change package has been rejected by at least 

one reviewer. 

125 of 457

--state=[discarded] specifies that the change package has been discarded. 

--state=[commitfailed] specifies that the change package has failed to commit to the 

repository. 

-summary=value 

specifies a brief summary of the change package being edited. 

issue... 


issue identifies a specific issue that contains all change packages that you want to edit; use 

spaces to specify more than one issue. 

issue:change package id identifies a specific change package to edit; use spaces to specify 


DIAGNOSTICS 

See the diagnosticsreference page for possible exit status values. 

PREFERENCES 



SEE ALSO 

Commands: 

si discardcp, si opencp, si closecp, si createcp, si add, si ci, si co, si 

cpissues, si createcp, si drop, si lock, si viewcps 



126 of 457

si exit 

exits the current MKS Source Integrity client session 

SYNOPSIS 

si exit [--[no]abort] [--[no|confirm]shutdown] [(-?|--usage)] 




DESCRIPTION 

si exit exits the current Source Integrity client session. When you run any Source Integrity 

command from the CLI, or when you open the Integrity Client GUI, you start a client session. Only 

one client session is running at a time, regardless of how many GUI windows you have open or 

how many CLIs you are using. To close the GUI you use the appropriate menu commands, and to 

close the CLI you use the si exit command. In both cases you may have the further option of 

shutting down the Source Integrity client altogether, based on your preferences (see si 

setprefs); if you do not, the client is still running and available for additional interaction. If you do 

shut down the client completely, then running any Source Integrity command from the CLI or 

opening the Integrity Client GUI starts a new client session. 

Options 



--[no]abort 

controls whether to shut down any other Source Integrity commands that may be running. 

Some commands allow you to specify a --persist option which keeps those commands 

active during a client session. Using --abort with si exit is recommended for stopping 

all persistent views that have been specified with another command's --persist option. 

--[no|confirm]shutdown 

controls the shutting down of the Source Integrity client without getting a prompt. 

Note: 

DIAGNOSTICS 

Specifying --noshutdown with si exit is essentially a non-operation: it does 

nothing. 

127 of 457


PREFERENCES 



SEE ALSO 

Commands: 

si about, si gui, si setprefs 



128 of 457

si freeze 

freezes a project member 

SYNOPSIS 

si freeze [(-R|--[no|confirm]recurse)] [--filter=filteroptions] 






DESCRIPTION 

si freeze freezes one or more project members. If no members are specified, si freeze 

assumes all members of the project. Members can be unfrozen with the si thaw command. 

When a member is frozen, all MKS Source Integrity operations are run on the frozen member 

revision. The member revision and attributes of the frozen member cannot be changed until it is 

thawed. This ensures that a particular revision is always picked up, even if development on it 

continues. 

Options 



member... 


DIAGNOSTICS 


PREFERENCES 



SEE ALSO 

129 of 457

Commands: 

si checkpoint, si thaw 



130 of 457

si gui 

starts the Integrity Client graphical user interface 

SYNOPSIS 

si gui [--height=value] [--width=value] [-x value] [-y value] [(-?|--usage)] 




DESCRIPTION 

si gui starts the Integrity Client graphical user interface. 

Options 




specifies the height of the GUI window, in pixels; value must be a whole number. 

--width=value 

specifies the width of the GUI window, in pixels; value must be a whole number. 

-x value 

used with the -g or --gui options, specifies the x location in pixels of the window. 

-y value 

used with the -g or --gui options, specifies the y location in pixels of the window. 

DIAGNOSTICS 


PREFERENCES 



SEE ALSO 

131 of 457



132 of 457

si import 

imports a member from a server file or from an old Source Integrity archive into an existing MKS Source 

Integrity project 

SYNOPSIS 

si import [--archive=filename] [--author=name] [(--binaryFormat|--textFormat)] 

[(-d desc|--description=desc)] [--descriptionFile=file] [--devpath=path] [--[no]createSubprojects] 

[--[no]unexpand] [(-r rev|--revision=rev)] [(-P project|--project=project)] 

[( -S sandbox|--sandbox=sandbox)] 

[--hostname=server] [--port=number] [--password=password] [--user=name] [--cwd=directory] [(-F file|-selectionFile=file)] 


[--settingsUI=[gui|default]] [--status=[none|gui|default]] [(-?|--usage)] [(-Y|--yes)] [--cpid|-changepackageID=value] 

[--[no|confirm]closeCP] [--[no]defer] [--issueID=value] 

[-R|--[no|confirm]recurse] [--[no|confirm]includeFormers] [--exclude=file:pattern,dir:pattern...] 

[--include=file:pattern,dir:pattern...] nonmember... 

DESCRIPTION 

si import imports an external file or archive into the Source Integrity repository and adds it as a member of a 

Source Integrity project. 

The si import command can be used for the following: 

● Import archives from older versions of Source Integrity into an existing project on the Integrity Server. 

Note: Once a member has been imported, you may not use an older version of Source Integrity to manipulate 

its archives. 

● To add several files as new members more quickly. Use the si import command for batch imports of a 

directory tree. 

Place the files on the server in the project directory before si import is run. The files can safely be removed 

after the command completion. 

Note: To retrieve a dropped member history, use the si addmemberfromarchive command. 

Options 



--archive=filename 

sets the archive file name, filename, containing the server-side path and name by which the newly added 

member will be archived. This must be an existing archive file - this option does not create a new archive. This 

is an advanced option that effectively specifies an archive path to override the default mapping, allowing a 

basic form of archive sharing between projects; its use is not recommended except by advanced Source 

Integrity administrators. 

-r=value 


specifies the revision at which the member is to be added. This must be an existing revision in the archive. By 

133 of 457

default, the member is added at the latest revision on the main branch. 

--author=name 


--binaryFormat 

--textFormat 

forces the storage of the member file to occur in binary format or text format. This option overrides the 

preferences settings that control default behavior in the application for storage format. See the si setprefs 

and si viewprefs commands for more details on preferences. 


identifies the name of the development path. 

-d desc 


specifies a description for the new member history; this setting and the --descriptionFile option are 

mutually exclusive. If specifying a nonmember that has an existing history, this description does not overwrite 

an existing description and is ignored. 


specifies a file for obtaining a description to apply to the new member history; this setting and the 

--description option are mutually exclusive. If specifying a nonmember that has an existing history, this 

description does not overwrite an existing description and is ignored. 


controls whether to create subprojects for each subdirectory encountered when adding members. This option is 

commonly used where you anticipate working with a large directory structure, because multiple subprojects are 

easier to manage than many subdirectories within one project. For example, specifying: 

si import --createSubprojects --description="Button Application" 



option, the file and its path simply would be added to the project in the project directory. 


controls whether to unexpand keywords in the member file before checking it into the history. Keyword 

expansion is only available in text archives, not binary archives. For descriptions of the Source Integrity 

keywords, see the Source Integrity Enterprise User Guide User Guide. Possible keywords are: 

$Author$ 

$CompanyInfo$ 

$Date$ 

$Header$ 

$Id$ 

$Locker$ 

$Log$ 

$Name$ 

$ProjectName$ 



$RCSfile$ 

$Revision$ 



$Source$ 

$State$ 

134 of 457

--cpid=value 


identifies a change package that is notified of this action, for example, 1452:1. Note the following about using 

this option: 


❍ You must specify this option if you have requested to obtain a lock and TrackLocks is enabled, and/or it 

is mandatory to specify a change package. 

❍ If you have TrackLocks enabled, Source Integrity prompts you with the change package you used when 

you checked out the specified member, not the default change package. From the graphical user 

interface, you must manually select the change package. 



❍ The next time you are prompted for a change package ID, the last used change package ID is displayed 

by default, if :none was specified or at least one change package was successfully updated from the last 

operation. 





--[no]defer 

controls whether to delay the operation in the project until the deferred operation is submitted. The operation in 

the sandbox still takes place immediately. 


controls whether to include former members when importing. 

-R 


controls whether to select non-members recursively. Non-members are files that exist in the sandbox directory 

but have not previously been added to the server repository. 





monmember... 

identifies a specific file to add to your sandbox; use spaces to specify more than one. The file pathnames are 

server-side, relative to the project. 

Note: All files must be added "in tree", that is, the nonmember must exist in the sandbox directory or a 

subdirectory. Shared "out of tree" histories are supported by using the --archive option to point to the "out of 

tree" history that you want to associate with the member. 

DIAGNOSTICS 


PREFERENCES 


135 of 457

SEE ALSO 

Commands: 

si add, si addmemberfromarchive 



136 of 457

si importproject 

imports an external project and registers it on an Integrity Server 

SYNOPSIS 

si importproject [--[no]openView] [--hostname=server] [--port=number] 




[--[no]add] project location... 

DESCRIPTION 

si importproject imports an external project into the Integrity Server and adds it as a top-level 

project. All existing legacy projects must first be imported before further commands can operate on 

the project and its members. If you only want to expose a project already in the Source Integrity 

repository, such as exposing a subproject as a top-level project, use the si addproject 


This command would normally be run only by the Source Integrity administrator. 

An existing project may have been created by a prior version of Source Integrity, or dropped, or 

copied from another server. However, this operation is strictly performed on the Integrity Server -- 

all archives and projects must have been copied to the appropriate location on the server. They are 

NOT copied up from a client. 

The processing of this command may take some time, since it traverses all subprojects in the 

imported project, and may perform various operations on them, such as checkpointing. 

The Source Integrity administrator may restrict the path names of projects being imported on the 

server. This is done through the si.serverRoot property in the si.properties file on the Integrity 

Server. If this is set, then any project location given must be under that directory. For details, see 

the Integrity Server Administration Guide. 

Note: 

Options 

Once a project has been imported, you may not use an older version of Source Integrity to 

manipulate it nor its archives. If for some reason you need to use an older version of Source 

Integrity on a project, first use si dropproject before doing so. The project must be reimported 

before it can be used again with this version of Source Integrity. 

137 of 457




controls whether to open the project view after this project is imported and registered on the 

server. If --noopenView is used, the project view does not open. 

--[no]add 

specifies if to add the project to the list of registered projects. 

project location... 

identifies a location on the Integrity Server for the existing project to be imported. 

Regardless of your operating system, all paths are specified here using forward slashes (/) 

and should include the name of the project file (typically project.pj). Use spaces to 

specify more than one project location. 

DIAGNOSTICS 


PREFERENCES 



SEE ALSO 

Commands: 

si addproject, si checkpoint, si createproject, si createsandbox, si 

createsubproject, si dropproject, si importsandbox, si projects, si 

viewproject 



138 of 457

si importsandbox 

imports an existing sandbox 

SYNOPSIS 

si importsandbox [--[no]openView] [(-S sandbox|--sandbox=sandbox)] 




[--settingsUI=[gui|default]] [--status=[none|gui|default]] file... 

DESCRIPTION 

si importsandbox imports an existing sandbox and registers it as a new sandbox on the 

Integrity Client. You must correlate this sandbox with a project that already exists on the Integrity 

Server, and it is assumed that the project you identify is the project the sandbox was first created 

from. A sandbox must first be registered before further commands can operate on the sandbox and 

its members. 

Options 




controls whether to open the sandbox view after this sandbox is imported and registered on 

the client. If --noopenView is used, the sandbox view does not open. 

file... 

identifies an existing sandbox file (project.pj) on the MKS Source Integrity client system 

to be imported; use spaces to specify more than one. 

Note: 

Unlike the si createsandbox command, for si importsandbox you must 

include the name of the sandbox file, which is typically project.pj. 

DIAGNOSTICS 


PREFERENCES 

139 of 457



SEE ALSO 

Commands: 

si add, si createproject, si dropsandbox, si importproject, si 

sandboxes, si viewsandbox 



140 of 457

si integrations 

manages integrations. 

SYNOPSIS 

si integrations [--action=[list|enable|enableAll|disable|disableAll]] [(-?|--usage)] 



[--status=[none|gui|default]] string... 

DESCRIPTION 

si integrations enables or disables Source Integrity Integrations. You can select from a list of 

available IDE integrations and enable or disable them as required to work with your preferred IDE. 

There is no requirement to re-install the Integrity Client, but if prompted, you may need to reboot 

your computer or restart the IDE for the integration to take effect. 

An Integrated Development Environment, or IDE, is a supported development application, such as 

Sybase PowerBuilder, that allows you to access Source Integrity functionality by installing the 

appropriate extension. 

For complete information on using third party integrations with Source Integrity, see the 

Integrations User Guide. 

Options 



--action=[list|enable|enableAll|disable|disableAll] 

specifies the action to perform on the integration. An action must be specified. There is no 

default specification for this option, so to list all of the available integrations, use the list flag. 

Note: Source Integrity asks you to restart your computer to complete the integration 

changes. If you are disabling[enabling] a number of integrations, you do not need to restart 

between each si integrations command. When you have disabled[enabled] all the 

required integrations, you can restart your machine. 

string... 

specifies the integration to perform an action upon. 

DIAGNOSTICS 

141 of 457


PREFERENCES 



SEE ALSO 



142 of 457

si loadrc 

loads the Integrity Client preferences file 

SYNOPSIS 

si loadrc [--[no]merge] [--rc=value] [(-?|--usage)] [(-N|--no)] [(-Y|--yes)] 

[--[no]batch] [--cwd=directory] [--forceConfirm=[yes|no]] [-F|--selectionFile=value] 

DESCRIPTION 

si loadrc loads the user's IntegrityClient.rc file, which contains your personal 

preferences for configuring the Integrity Client. The IntegrityClient.rc file is loaded when 

you start the client; however, this command reloads the file without restarting the client. If for some 

reason your personal IntegrityClient.rc file has changed, this command will reload your 

preferences. Your preferences file shouldn't change, unless you happen to copy someone else's 

file or if you happen to restore a backup that you made. 

Your administrator can lock certain preferences from the Integrity Server, preventing you from 

configuring them using the si setprefs command. Preferences that are locked -- viewable with 

si viewprefs -- display (locked) at the end of the output line. The following preferences can 

be locked from the server by editing Source Integrity policies in the Administration Client: 

Tip: For information on editing Source Integrity policies, see "Configuring the Integrity Server" in 

the Integrity Server Administration Guide. 

Preference Affected Commands 

branchIfVariant si co , si lock 

breakLock si unlock 

changePackageID si co, si lock 

createBranch si lock 

onLock si co 

restoreTimestamp 

si resync, 

si resynccp, si 

revert 

retainWorkingFile si add, si ci 

saveTimestamp si add, si ci 

sparse si importsandbox 

143 of 457

updateMemberRev si ci 

Warning: Do not edit the IntegrityClient.rc file manually, because preferences that appear 

more than once in the IntegrityClient.rc file can cause the Integrity Client to behave 

unpredictably. 

Options 



--[no]merge 

controls whether settings from the loaded file should be merged into existing preferences. 

--rc=value 

identifies the file containing settings for running the Integrity Client. The default is the 

IntegrityClient.rc file in your home directory. 

DIAGNOSTICS 


PREFERENCES 



SEE ALSO 

Commands: 

si setprefs, si viewprefs 



144 of 457

si locate 

displays where a project, subproject, member, or revision is used 

SYNOPSIS 

si locate [--depth=[current|build|all]] [--devpathscope=[this|others|all]] 

[--distinct=[project|devpath|registeredproject]] 

[--[no]limittoactiveprojects] [--listfields=field1[:width1],field2[:width2]...] 

[--mode=[distinct|list]] [--projectscope=[this|others|all]] 

[(-r value|--revision=value)] [--height=value] [--width=value] [-x=value] [-y=value] 



[--user=name] [(-?|--usage)] [(-N|--no)] [(-Y|--yes)] [--[no]batch] [--cwd=directory] 


[--status=[none|gui|default]] member/subproject 

DESCRIPTION 

As projects grow in complexity, it can be difficult to determine the relationships that Source Integrity 

objects--projects, subprojects, and members--have with one another. When working with multiple 

development paths and shared subprojects or shared member archives, it becomes very important 

to understand what areas of a project might be affected by parallel development. Using the si 

locate command, you can locate where a specific Source Integrity object is used in your source 

code repository and refine and sort the search results. 

For example, you might need to: 

● Determine what “active” projects (a project currently under development) a member, 

subproject, or registered top-level project is shared into. 

● Determine what development paths a selected member or subproject is a part of. 

● Determine if a selected member revision is part of a checkpoint. 

● Confirm all existing checkpoints for a selected revision before you delete it. 

● Display the development path that a corresponding member revision belongs to. 

● Display which master projects a selected subproject belongs to. 

Source Integrity displays the search results in one of the following modes: 

● Distinct Mode provides a high-level view of the information. 

● List Mode provides a detailed view of the information. 

Key Considerations: 

145 of 457

● The si locate command can only be used in the database repository. Using the 

command in the RCS based repository returns an error message. 

● You require the OpenProject permission for the project you are running the si locate 

command from. When the Locate view displays, Source Integrity informs you if there are 

additional projects that you do not have permission to view. 

● Archive locations are not displayed in the search results. 

Options 



--depth=[current|build|all] 

specifies the depth of the search. --depth=current searches current project 

configurations (normal and variant).--depth=build searches current project 

configurations and checkpoints.--depth=all searches current project configurations, 

checkpoints, and in between checkpoints. 

--devpathscope=[this|others|all] 

specifies which development paths to include in the search. --devpathscope=this 

searches the current development path. --devpathscope=others searches all 

development paths, except the current development path. --devpathscope=all 

searches all development paths. 

--distinct=[project|devpath|registeredproject] 

specifies the information you want displayed in Distinct Mode. This option must be used with 

--mode=distinct. --distinct=project lists only distinct project names.-distinct=devpath 

lists only development path names.-distinct=registeredproject 

lists only registered top-level project names. 

--[no]limittoactiveprojects 

specifies whether to search projects referenced by current registered top level projects on 

the server. 

--listfields=field1[:width1],field2[:width2]... 

allows you to select fields to be displayed when you use the --mode=list option, specified 

in the format field1[:width1],field2[:width2].... Specifying the column [: width] (in pixels) for 

each field is optional - widths are only available in the GUI. In the CLI, fields are separated 

with a space. This option must be used with --mode=list. 

You can display one or more of the following fields: 

checkpoints 

displays the checkpoints that the object belongs to. 

dates 

displays the date ranges in which the object exists. 

devpath 

displays the development paths that the object belongs to. 

146 of 457

name 

displays the object's path and name. 

project 

displays the projects that the object belongs to. 

revisions 

displays the member's revisions. 

registeredproject 

displays the top-level project that the object belongs to. 

--mode=[distinct|list] 

specifies the level of detail to display in the search results. --mode=distinct displays 

only the projects and/or development paths that contain the object you are searching. This 

option must be used with --distinct=[project|devpath|registeredproject]. -mode=list 

displays all occurrences of the object in the projects and/or development paths 

that contain the object. If you do not specify a mode, --mode=distinct and -distinct=devpath 

are used. 

--projectscope=[this|others|all] 

specifies which projects to search. --projectscope=this searches the current project 

and its subprojects.--projectscope=others searches all projects and subprojects, 

except the current project.--projectscope=all searches all projects and subprojects. 

-r 

--revision 

specifies the member revision to search. 


used with the -g or --gui options, specifies the height of the GUI window, in pixels; value 

must be a whole number. 

--width=value 

used with the -g or --gui options, specifies the width of the GUI window, in pixels; value 

must be a whole number. 

-x value 


-y value 


member/subproject 

locates where the specified member or subproject is used. If you do not specify a member 

or subproject, Source Integrity uses the project specified in -P project|--project=project 

or -S sandbox|--sandbox=sandbox. 

DIAGNOSTICS 


PREFERENCES 

147 of 457



SEE ALSO 

Commands: 

si deleterevision, si viewproject, si viewprojecthistory, si 

viewhistory 



148 of 457

si lock 

locks project members 

SYNOPSIS 

si lock [--[no|confirm]branch] [--[no|confirm]branchVariant] 

[(--cpid ID|--changePackageId=ID)] [--issueId =ID] [(-r rev|--revision=rev)] 







DESCRIPTION 

si lock locks one or more project members. If no members are specified, si lock applies to all 

project members. By default, the member revision is locked and not necessarily the working 

revision, if in a sandbox. 

This is purely a project operation -- if performed in a sandbox, no memory of what revision was 

locked is maintained in the sandbox. 

Depending on the locking policy configured by your administrator, you may hold a lock on only one 

revision of a particular member at a time. It is not an "error" to relock an already locked member. 

If the target revision is already locked by a user other than yourself, then specifying the --branch 

option creates a branch revision and locks it. Otherwise, you cannot lock the revision at all. 

Options 



--[no|confirm]branch 

controls whether to create a branch revision if the target revision is already locked by a user 

other than yourself. 

For details on branch revisions, see the si ci reference page. 


controls whether to create a branch off of the revision you are locking, if you are working in a 

variant sandbox. This is useful for keeping changes in the variant separate from changes 

149 of 457

made in the mainline project. 

--cpid=ID 


identifies a change package that is notified of this action, for example, 145:2. Note the 










--issueId=ID 




package ID. This option can only be specified if the Integrity Manager integration is enabled. 

See the Integrity Server Administration Guide or your administrator for details on using the 

Integrity Manager integration. 

member... 


DIAGNOSTICS 


PREFERENCES 



SEE ALSO 

Commands: 

si ci, si co, si edit, si rlog, si unlock 



150 of 457

si locks 

displays a user's locks. 

SYNOPSIS 

si locks [--locker=value] [--fields=field1[:width1],field2[:width2]...] [--height=value] 

[--width=value] [-x=value] [-y=value] [--hostname=server] [--port=number] 



[(-g|--gui)] [--quiet] [--settingsUI=[gui|default]] [--[no]persist] 


DESCRIPTION 

si locks displays all of a user's locks on the target server. 

Options 



--locker=value 

specifies the user whose locks are retrieved. 



archive 

displays the name of the locked archive. 

cpid 

displays the change package ID number if it is a lock entry in a change package. 

devpath 

displays the name of the development path where the lock on the revision was made 

from. This information is relevant when the locking policy is set to devpath, allowing a 

single user to have a single lock on an archive per development path. 

host 

displays the hostname of the computer which the lock was performed on. 

member 

displays the name of the locked member. 

project 

displays the name and path of the project where the member revision was locked 

from. If the member revision was locked from a shared subproject, it is the subproject 

151 of 457

name and path that are displayed. 

revision 

displays the locked revision number. 

sandbox 

displays the name of the sandbox where the lock on the revision was made, and is 

relevant when viewing the information from the machine that locked it. 

timestamp 

displays the time the archive was locked. 

user 

displays the user holding the lock. 


specifies the height of the GUI window in pixels. 

--width=value 

specifies the width of the GUI window in pixels. 

-x=value 

specifies the x location of the GUI window in pixels. 

-y=value 

specifies the y location of the GUI window in pixels. 

--[no]persist 


DIAGNOSTICS 


PREFERENCES 



SEE ALSO 

Commands: 






152 of 457

si makewritable 

makes sandbox members writable 

SYNOPSIS 

si makewritable [(-R|--[no|confirm]recurse)] [--filter=filteroptions] 






DESCRIPTION 

si makewritable makes sandbox members writable. If no members are specified, si 

makewritable applies to all sandbox members. 

The si makewritable command makes a working file writable. This option is useful when you 

want to work with a particular revision and someone else has the revision checked out, but you do 

not want to create a new branch. When the other user has completed their changes and checked 

them in, you can check out the revision, merge your changes with the new revision, and check in 

your changes. This option is equivalent to the si co --onLock=makewritable command. 

Options 





DIAGNOSTICS 


PREFERENCES 



153 of 457

SEE ALSO 

Commands: 

si ci, si co, si diff, si edit, si lock, si resync, si rlog, si unlock 



154 of 457

si memberinfo 

lists member information 

SYNOPSIS 

si memberinfo [--[no]acl] [--[no]attributes] [--[no]changePackage] 

[--[no]labels] [--[no]rule] [(-P project|--project=project)] 





[--status=[none|gui|default]] member 

DESCRIPTION 

si memberinfo lists current information about a project member. This includes general 

information about the member, and specific information on the member revision. For example: 



The member archive is shared 

Member Revision: 1.7 

Created By: sueq on July 11, 2005 - 11:36 AM 

State: state_a 

Revision Description: 

Updated for Technical Review 

Labels: 

TechReview1 

Change Package: 

ID: 1:1 

Summary: Search Engine Fix 

Attributes: none 

This member does not have a revision rule. 

Note: The member archive is shared displays only if the member shares another member's 

archive and you are using the database repository. 

Options 



155 of 457

--[no]acl 

shows ACL information for the member. 

--[no]attributes 

controls whether to display member attributes. If no attributes exist, Attributes:none is 

displayed. 

--[no]changePackage 

controls whether to display change package information (applies only change packages are 

enabled). 

--[no]labels 

controls whether to display member labels. 

--[no]rule 

controls whether to display the member revision rule. 

member 

identifies one specific member. 

DIAGNOSTICS 


PREFERENCES 



SEE ALSO 

Commands: 

si archiveinfo, si mods, si revisioninfo, si rlog, si setmemberrule, si 

updatemember 



156 of 457

si merge 

merges data from two revisions of a project member into a working file 

SYNOPSIS 

si merge [--mergeType=[confirm|cancel|automatic|manual]] 

[--onMergeConflict=[confirm|cancel|mark|launchtool|highlight|error]] [--outputFile=value] 

[-r rev] [--resolve] [(-R|--[no|confirm]recurse)] [--filter=filteroptions] 






DESCRIPTION 

si merge merges data from two revisions of a project member against a root revision. By default, 

the result overwrites the working file. This operates in a sandbox. You cannot perform a merge on 

a project-only basis, since the result is left in your sandbox. 

The second -r rev specified is merged with the revision in the current working file. The first 

-r rev specified is the root revision. Both the working file revision and the other revision should 

have been derived from this root revision. For example, suppose development has branched from 

revision 1.3, with maintenance occurring on the 1.3.1 branch. Further suppose the tip of that 

branch is revision 1.3.1.3, the headrev member revision is 1.5, and that the revision in the sandbox 

is 1.5. 

1.5 (headrev) 

1.4 

1.3.1.3 (maintenance branch tip) 

1.3.1.2 

1.3.1.1 

1.3 (root) 

The command si merge -r 1.3 -r 1.3.1.3 merges the changes in 1.3.1.3 that have occurred 

since 1.3, into revision 1.5 in the working file in the sandbox. 

si merge is useful for combining separate changes into a checked out revision. Suppose root is 

the original, and both headrev and branch tip are modifications of root. Then, si merge combines 

both changes. 

An overlap occurs if both branches of development (headrev and branch tip) have changes in a 

157 of 457

common segment of lines. Depending on the value used in --onMergeConflict, si merge 

displays how many overlaps occurred, and includes both alternatives in the result, delimiting them 

as follows: 

> file2 

If there are overlaps, by default Source Integrity asks you how you want to resolve the conflict. If 

you specify --mergeType=automatic and --onMergeConflict=highlight, it is up to you 

to determine how to resolve the conflict by editing the result. 

Options 




specifies how you want to complete the merge. 



--mergeType=automatic completes the merge process without launching the MKS Visual 

Merge tool. 

Warning: While Source Integrity and MKS Visual Merge are capable of performing 

automatic merging, MKS cannot guarantee that the merged results are “correct”. MKS 

recommends that you examine and test the merged results before checking them into the 

repository. 

--mergeType=manual completes the merge operation through the MKS Visual Merge tool. 

The MKS Visual Merge tool launches, displaying the revisions you want to merge. For more 

information on the MKS Visual Merge tool, refer to the Source Integrity Enterprise User 

Guide. 

--onMergeConflict =[confirm|cancel|mark|launchtool|highlight|error] 

specifies what to do when conflicts occur during the merge. 


158 of 457


--onMergeConflict=mark marks the working file in your sandbox indicating that merging 

is required without completing all of the merge related tasks. This provides the time to 

investigate conflicts, edit, or difference blocks before finishing the merge. 

Tip: To display the affected member revisions, use the 

si print --filter=unresolvedmerges command. After you resolve the merge 

conflicts, merge the revisions using the si merge --resolve command. 

--onMergeConflict=launchtool launches the MKS Visual Merge tool to resolve the 

conflicts, all non-conflicting blocks will already have been applied. 

--onMergeConflict=highlight indicates conflicts in the working file with the following 

characters: "". You are responsible for manually resolving conflicts in 

the working file. 


--onMergeConflict=error displays an error when a merge conflict is encountered. 

--outputFile=value 

identifies the location and name of a file that is to contain the result of merging data from two 

member revisions. If you do not specify a file, the working file is used. 

-r rev 

uses a specified revision. value can be a valid revision number or a label. 

Specify this option twice to identify the two revisions to be merged; the first instance is the 

"old" revision, the second is the "new". The changes needed to make the "old" into the "new" 

are then incorporated into the working file or into the --outputFile. If you specify the 

-r rev option only once, si merge uses the latest revision on the default branch as the 

other revision. 

--resolve 

merges a previously unresolved merge. 



DIAGNOSTICS 


159 of 457

PREFERENCES 



SEE ALSO 

Commands: 

si ci, si co, si diff, si mergebranch, si revisioninfo 



160 of 457

si mergebranch 

merges a branch revision into a single revision 

SYNOPSIS 

si mergebranch [--[no|confirm]branch] [--[no|confirm]branchVariant] 

[--mergeType=[confirm|cancel|automatic|manual]] 

[--onMergeConflict=[confirm|cancel|mark|launchtool|highlight|error]] 

[--branchRevision=value] [(--cpid ID|--changePackageId=ID)] [--issueId=ID] 

[(--[no]lock)] [--targetRevision=value] [(-R|--[no|confirm]recurse)] 

[--filter=filteroptions] [(-S sandbox|--sandbox=sandbox)] [--hostname=server] 




[--status=[none|gui|default]] sandbox member... 

DESCRIPTION 

si mergebranch allows you to combine the development occurring on different branches by 

merging the branched revisions into a single revision. 

Source Integrity recognizes cases where a previous merge has occurred, (whether by merging the 

branch, automatic merging, or using the MKS Visual Merge and MKS Visual Difference tools), and 

merges only changes since the last merge operation. Thus, the first merge branch operation 

occurring on a given branch merges all changes throughout the branch. Any subsequent merge 

branch operations will merge only changes since the previous merge operation. 

Options 



--[no|confirm]branch 

specifies whether to create a branch off of the target revision (the member revision that the 

working revision is merged into), if it is locked by another user. 


specifies whether to create a new branch for the merged revision, if the specified variant 

does not already have a branch. 


specifies how you want to complete the merge. 


161 of 457



Merge tool. 

Warning: While Source Integrity and MKS Visual Merge are capable of performing 



repository. 




Guide. 

--onMergeConflict=[confirm|cancel|mark|launchtool|highlight|error] 

specifies what to do when conflicts occur during the merge. 



--onMergeConflict=mark marks the working file indicating that merging is required 

without completing all of the merge related tasks. This provides the time you may need to 

investigate conflicts, edit, or difference blocks before finishing the merge. 



--onMergeConflict=highlight indicates conflicts in the file with the following characters: 

"". You are responsible for manually resolving conflicts in the working 

file. 


--onMergeConflict=error displays an error when a merge conflict is encountered. 

--branchRevision=revision 

specifies the branch revision that you want to merge into the head revision. If no revision is 

specified, the working revision is used. 

--cpid=ID 


162 of 457






❍ If the Integrity Manager integration is enabled, but it is not mandatory to specify a 

change package, or if no change package is applicable, you must specify 

--changePackageId=:none. 




--issueId=ID 


another way of redirecting to a change package. If you have an issue assigned to you that 

contains one open change package, you can specify the issue ID instead of the change 




--[no]lock 

controls whether to lock the target revision, so that the results of the merge can be checked 

in. 

--targetRevision=revision|:symbolic 

specifies the symbolic name (i.e. member, working, branch, etc.), revision number, or label 

of the revision that you want to merge the branch revision into; typically the head revision. If 

no revision is specified, the member revision is used. 



DIAGNOSTICS 


PREFERENCES 



SEE ALSO 

Commands: 

163 of 457

si ci, si diff, si edit, si lock, si merge, si resync, si rlog, si unlock 



164 of 457

si mods 

lists changes made to a project since a checkpoint 

SYNOPSIS 

si mods [--fields=field1[:width1],field2[:width2]...] [(-r rev)] [--[no]showAppliedCPList] 

[--[no]showAttrChanges] [--[no]showChangePackages] [--[no]showMemberChanges] 

[--[no]showRevDescription] [--devpath=value] [--projectRevision=value] 

[(-R|--[no|confirm]recurse)] [(-P project|--project=project)] 


[--password=password] [--user=name] [--height=value] [--width=value] [-x=value] 

[-y=value] [(-?|--usage)] [(-F file|--selectionFile=file)] [(-N|--no)] [(-Y|--yes)] 



DESCRIPTION 

si mods displays modifications to a project between checkpoints or between a checkpoint and the 

working project. 

Options 








The fields available can be one or more of the following: 

change 

displays details of changes made to project members. 

name 

displays the member name. 

-r rev 

uses a specified revision of the project. rev can be a valid revision number or label. The -r 

option may occur twice; if the second is not specified, the comparison is against the working 

project. If both revisions are not specified, the first revision is the tip of the trunk in a normal 

project, or the project revision when working in a variant sandbox. For example, simply 

165 of 457

using si mods shows all the changes in the current project since the last checkpoint. 

--[no]showAppliedCPList 

controls whether to show change packages applied to a project via si applycp or si 

resynccp. 

For more information on applying change packages, see si applycp. 

--[no]showAttrChanges 

controls whether to show the member attribute changes. 

--[no]showMemberChanges 

controls whether to show member changes. 

--[no]showRevDescription 

controls whether to show the revision description of new revisions that have been added. 

--[no]showChangePackages 

controls whether to show the change packages that correspond to member operations. 

Change package information displayed is drawn from the modifications calculated from the 

checkpoint comparison. 

The By Change Package panel displays the following information: 

❍ ID displays the change package ID for change packages that contain entries with 

member changes between project revisions 

❍ Summary displays the change package summary for change packages that contain 

entries with member changes between project revisions. 

Modifications that are not associated with a change package (unresolved) are displayed in 

the bottom frame of the By Change Package panel. Where possible, the member or project 

name is displayed with full path information. The following are reasons why modifications 

can appear in the bottom frame: 

❍ The change package entry is missing; either because one was not recorded for the 

member operation, or the entry was discarded. 

❍ The operation that made the modification cannot use a change package, for example, 

adding a subproject. 

❍ The project state captures compared are from different development paths. 

Pending change package entries do not appear in the By Change Package panel (GUI). 

-R 


controls whether to recurse into subprojects that are determined to be in common between 

the two projects. 


specifies the height of the GUI window, in pixels; value must be a whole number. 

--width=value 

166 of 457

specifies the width of the GUI window, in pixels; value must be a whole number. 

-x=value 

specifies the x location of the GUI window in pixels. 

-y=value 

specifies the y location of the GUI window in pixels. 

DIAGNOSTICS 


PREFERENCES 



SEE ALSO 

Commands: 

si appendrevdesc, si archiveinfo, si checkpoint, si ci, si co, si diff, si 

memberinfo, si merge, si projectinfo, si revisioninfo, si rlog, si 

sandboxinfo, si updatearchive, si updaterevision, si viewhistory 



167 of 457

si move 

moves one or more project members between projects, or between directories in a single 

project 

SYNOPSIS 

si move [(--cpid ID|--changePackageId=ID)] 

[--[no|confirm]closeCP] [--[no]confirm] [--[no]defer] [-f] [--issueId=ID] 

[--[no]moveWorkingFile] [--[no|confirm]overwrite] [--[no]createSubprojects] 

[--targetDevpath=value] [--targetDir=value] [--targetProject=value] 

[--targetSandbox=value] [--filter=filteroptions] [(-P project|--project=project)] 






DESCRIPTION 

As software designs and project structures change, it may become necessary to move one or more 

members between projects, variants of the same project, or directories in a project. 

Moving a member performs a drop in the source location and an add in the target location, creating 

a new revision in the existing archive. The member’s archive remains in its original location in the 

repository so that change packages, member histories, and project histories continue to work. If 

the move is performed with a change package, the member is added as a single Move entry in the 

change package. If you are moving multiple members, any common directory prefix shared by the 

members is automatically removed during the move. 

Key Considerations 

● Moving members between projects on different servers is not supported. 

● You can perform deferred member moves only if both the source and target locations are 

sandboxes. 

● si move does not work recursively on subprojects. To move one or more subprojects, use 

the si movesubproject command. 

● Source Integrity detects whether any ACLs exist in the tree defined by the source project, 

the target project, and the common root between them (or the global ACL, if there is no 

common root). If any ACLs are found, Source Integrity warns you so you can manually 

make any required adjustments to the ACLs after the move is complete. 

168 of 457

Options 



--cpid=ID 


















--[no]confirm 

controls whether to confirm the move before proceeding. 

--[no]defer 

controls whether to delay the move operation in the project until the deferred operation is 

submitted. The move operation in the sandbox still takes place immediately. This option is 

available only if the source and target are sandboxes. 

-f 

forces the move without confirmation. 

--issueId=ID 




package ID. This option can only be specified if the Integrity Manager Integration is enabled. 



--[no|confirm]overwrite 

controls whether to overwrite the working file if it exists. This option is valid only if you are 

169 of 457

moving one or more members from a source sandbox to a target sandbox. 

--[no]moveWorkingFile 

controls whether to move the working file into the sandbox immediately. This option is valid 

only if you are moving one or more members from a source sandbox to a target sandbox. 


controls whether to create subprojects in existing directories that do not contain subprojects. 

--targetDevpath=value 

specifies the target development path (for variant projects). 

--targetDir=value 

specifies the subdirectory in the destination project or sandbox’s directory that you want to 

move the member(s) to. 

--targetSandbox=value 

specifies the name of the target sandbox (can be used as a project redirector). 

--targetProject=value 


member... 

identifies a member to move; use spaces to specify more than one member. 

DIAGNOSTICS 


PREFERENCES 



SEE ALSO 

Commands: 

si co, si rename, si movesubproject 



170 of 457

si movesubproject 

moves a subproject between projects or between directories of a single project 

SYNOPSIS 

si movesubproject [--[no]confirm] [--[no]createSubprojects] [-f] 

[--moveWorkingFiles=[none|members|all]] [--[no|confirm]overwrite] 

[--targetDevpath=value] [--targetDir=value] [--targetProject=value] 

[--targetSandbox=value] [(-P project|--project=project)] 





[--status=[none|gui|default]] subproject or subsandbox 

DESCRIPTION 

To meet the needs of changing project configurations, you can move one or more subprojects, and 

all of its members and sub-subprojects, between projects, and/or directories in a single project, or 

variants of the same project on the same Integrity Server. 

When a subproject is moved, it behaves like a shared subproject. The subproject in the new 

location continues to be backed by the underlying subproject in the old location and the path and 

name of the subproject file in the repository remains the same. Any external references (ACL 

names, event triggers, policy statements) to the moved subproject continue to work because they 

are based on the subproject’s original name; however, a subproject that is moved into a new 

project hierarchy continues to inherit ACLs from its original hierarchy and not from the new parent 

project. The moved subproject also retains its configuration type (normal, variant, build). If you are 

moving multiple subprojects, any common directory prefix shared by the subprojects is 

automatically removed during the move. 

Before using si movesubproject, note the following: 

❍ Moving subprojects between projects on different servers is not supported. 

❍ The moved subproject inherits the project or directory ACLs from its original location. You 

cannot apply the ACLs from the new location to the subproject. 

❍ The path and name of the subproject file in the repository is permanently reserved. If you 

attempt to create a new subproject using the moved subproject’s path and name in the 

repository, you are prompted to add the existing subproject. If you answer no, the create 

subproject operation exits without providing you with the option of creating a subproject with 

a different path and name. 

❍ Deferred and pending subproject moves are not supported. 

171 of 457

❍ You can move one or more subprojects across directories within a single project. 

❍ Moved subprojects are not displayed as shared in a Sandbox or Project view unless the 

subproject was shared before the move. 

❍ When you move one or more subprojects, you cannot co-locate subprojects in the same 

directory. If you want to co-locate an existing subproject with another subproject, use the si 

sharesubproject command on the subproject you want to move, followed by si 

dropsubproject in the original location. 

Options 



--[no]confirm 

controls whether to confirm the move before proceeding. 


controls whether to create subprojects in existing directories that do not contain subprojects. 

-f 

force the move without confirmation. 

--moveWorkingFiles=[none|members|all] 

controls whether to move existing working files in the subproject. This option is valid only if 

you are moving one or more subprojects from a source sandbox to a target sandbox. 


controls whether to confirm before overwriting any existing working files that exist in the new 

location. This option is valid only if you are moving one or more subprojects from a source 

sandbox to a target sandbox. 


specifies the target development path (for variant projects). 

--targetDir=value 

specifies the subdirectory in the destination project or sandbox’s directory that you want to 

move the subproject(s) to. 

--targetProject=value 


--targetSandbox=value 

specifies the name of the target sandbox (can be used as a project redirector). 

subproject or subsandbox 

identifies a subproject or subsandbox to move; use spaces to specify more than one 

subproject 

DIAGNOSTICS 


172 of 457

PREFERENCES 



SEE ALSO 

Commands: 

si move, si sharesubproject, si dropsubproject 



173 of 457

si opencp 

reopens a change package 

SYNOPSIS 

si opencp [--hostname=server] [--port=number] [--password=password] [--user=name] 



[--settingsUI=[gui|default]] [--status=[none|gui|default]] issue|issue:change package id... 

DESCRIPTION 

si opencp reopens a change package. A change package is in the Open state when it is first 

created. This command is useful for reopening a change package after it has been submitted. 

The open state is the only state where you can add new entries to a change package. As part of 

the review workflow, change packages in the following states can be reopened: CommitFailed, 

Rejected, and Discarded. 

Caution: Only a Change Package Administrator can reopen a change package in the Closed 

state. Modifying closed change package contents can compromise the integrity of the repository. 

Options 



issue... 


issue identifies a specific issue that contains all change packages that you want to open; 


issue:change package id identifies a specific change package to open; use spaces to 


DIAGNOSTICS 


PREFERENCES 

174 of 457



SEE ALSO 

Commands: 

si cpissues , si createcp, si viewcps, si acceptcp, si rejectcp, si 

discardcp 



175 of 457

si print 

displays member information 

SYNOPSIS 

si print [--format=value] [--headerFormat=value] [--noFormat] [--noHeaderFormat] 

[--noTrailerFormat] [(-r rev|--revision=rev)] [--range=value] 

[--trailerFormat=value] [--fields=field1[:width1],field2[:width2]...] [--height=value] 

[--width=value] [-x value] [-y value] [(-R|--[no|confirm]recurse)] 





[--[no]persist] [--quiet] member... 

DESCRIPTION 

si print displays member information on the standard output. If you do not specify any 

members, si print displays all project members. This command is the same as si rlog; 

however, it has a different set of default options. In particular, --noFormat and 

--noTrailerFormat are specified, and --headerFormat=value produces one line per 

member. 

Options 

See the si rlog reference page for descriptions of all options applicable to si print. This 

command takes the universal options available to all si commands, as well as some general 

options - these are described on the options reference page. 

Note: The --headerFormat=value and --trailerFormat=value options only accept global 

fields. See si rlog for the list of global fields. Revision specific fields, such as State, cannot be 

used with these options. 

DIAGNOSTICS 


PREFERENCES 


176 of 457


SEE ALSO 

Commands: 

si archiveinfo, si diff, si memberinfo, si mods, si projectinfo, si 

report, si revisioninfo, si rlog, si sandboxinfo, si viewhistory 



177 of 457

si projectinfo 

lists project information 

SYNOPSIS 

si projectinfo [--[no]acl] [--[no]attributes] [--[no]devpaths] 






DESCRIPTION 

si projectinfo displays current project information, for example: 

Options 

Project Name: /rd/doc/MKS_Source_Integrity/Man_Pages/project.pj 

Server: server.mks.com:7001 

Revision: 1.1 

Last Checkpointed: Jul 18, 2002 - 4:14 PM 

Members: 83 

Subprojects: 0 

Description: Documentation Set 

Attributes: 

rd=/rd 

Development Paths: 

Variant Project for Docs Man Pages (1.1) 



--[no]acl 

shows ACL information for the project. 


controls whether to display project attributes. 

--[no]devpaths 

controls whether to display project development paths. 


displays project information ouput for a single revision of the project history. 

Note: 

178 of 457

DIAGNOSTICS 

The development paths (variants) may only be displayed through the master project, 

since you cannot have variants of variants. 


PREFERENCES 



SEE ALSO 

Commands: 

si viewproject, si viewprojecthistory 



179 of 457

si projects 

lists projects on the Integrity Server 

SYNOPSIS 

si projects [--[no]displaySubs] [--height=value] [--manage] [--width=value] 

[-x value] [-y value] [--hostname=server] [--port=number] [--password=password] 


[--[no]batch] [--cwd=directory] [--forceConfirm=[yes|no]] [(-g|--gui)] [--[no]persist] 

[--quiet] [--settingsUI=[gui|default]] [--status=[none|gui|default]] 

DESCRIPTION 

si projects displays a list of projects registered to the currently connected Integrity Server. A 

registered project is currently visible on the Integrity Server. A project dropped with the si 

dropproject command still exists on the Integrity Server, but does not display in the list of 

registered projects. 

Options 



--[no]displaySubs 

controls whether to display subprojects. By default, only top level registered projects are 

displayed. 


used with the -g or --gui options, specifies the height of the projects view window, in 

pixels; value must be a whole number. 

--manage 

enables the project manager view for those using the -g or --gui options. 

--width=value 

used with the -g or --gui> options, specifies the width of the projects view window, in 


-x value 


-y value 


--[no]persist 

controls whether this presentation of information should continue to be updated as new 

information becomes available. --nopersist forces a static "snapshot" of information, 

while --persist gives real-time updates. 

180 of 457

DIAGNOSTICS 


PREFERENCES 



SEE ALSO 

Commands: 

si createproject, si dropproject, si importproject, si projectinfo, si 

viewproject, si viewprojecthistory 



181 of 457

si promote 

promotes the state of a member 

SYNOPSIS 

si promote [(-r rev|--revision=rev)] [(-s state|--state=state)] 







DESCRIPTION 

si promote promotes a project member to a higher state of development. A state is a textual 


no state is assigned to a revision at check-in, a default value of Exp (for Experimental) is used. 


At particular milestones, project members are ready to move to the next state of their development 

cycle (for example, from Development to Testing). This is done through states and their promotion. 

Note: Promoting members is for historical purposes only. To more effectively control project 


Options 



-s state 

--state=state 

specifies the target state to be set for the promoted member. If no state is specified, the 

member is promoted to the next state. 

member... 


DIAGNOSTICS 


182 of 457

PREFERENCES 



SEE ALSO 

Commands: 

si demote, si demoteproject, si promoteproject 



183 of 457

si promoteproject 

promotes the state of a project 

SYNOPSIS 

si promoteproject [--[no|confirm]force] [(-s state|--state=state)] 






DESCRIPTION 

si promoteproject promotes a project to a higher state of development. A state is a textual 


no state is assigned to a revision at check-in, a default value of Exp (for Experimental) is used. 


Just as you can with a project member, you can promote the project itself (change its state, in 

other words). This can assist in management of an entire project through a development cycle, 

especially if the promotion functions are restricted to key project personnel. Normally, you promote 

a project (set its state) when you si checkpoint it, but you can do so at any time. Only the 

project is promoted, not the members of the project. 

Note: Promoting projects is for historical purposes only. To more effectively control project 


Options 



--[no|confirm]force 

controls whether to force promotion of a project even if members have been changed. 

-s state 

--state=state 

specifies the target state to be set for the promoted project. If no state is specified, the 

project is promoted to the next state. 

DIAGNOSTICS 

184 of 457


PREFERENCES 



SEE ALSO 

Commands: 

si demote, si demoteproject, si promote 



185 of 457

si rejectcp 

rejects a change package 

SYNOPSIS 

si rejectcp [--comments=value] [--commentsFile=value] 

[--reviewer=[user|group:|super]] [--hostname=server] [--port=number] 





DESCRIPTION 

si rejectcp rejects a change package under review. 

If a reviewer of a change package determines that additional development must be completed to 

resolve an issue, the reviewer can reject the change package. A single reviewer rejection is 

enough to reject a change package, even if there are multiple reviewers. The creator of the change 

package can reject it without being listed as a reviewer. 

An e-mail notification of the change package’s rejection is sent to the reviewers and creator. From 

the Rejected state, the change package can be discarded, or reopened. 

Options 



--comments=value 

specifies comments recorded in the review log with the vote. 

--commentsFile=value 

specifies a text file that contains the comments to be recorded in the review log with the 

vote. 

--reviewer=[user|group:|super|all] 

specifies the capacity in which you are rejecting the change package. 

user 

casts a vote as an individual reviewer in the reviewer list. 

group: 

casts a vote on behalf of the entire group (only one user from a group is necessary to 

vote on behalf of the entire group). 

186 of 457

super 

an overriding reject vote. A super reviewer is not required to be a listed reviewer for 

the change package. You must have the SuperReviewer permission to use this 

option. 

issue... 


issue identifies a specific issue that contains all submitted change packages that you want 

to reject; use spaces to specify more than one issue. 

issue:change package id identifies a specific change package to reject; use spaces to 


DIAGNOSTICS 


PREFERENCES 



SEE ALSO 

Commands: 

si co, si cpissues , si createcp, si viewcps si acceptcp, si opencp, si 

discardcp 



187 of 457

si rename 

renames an existing project member 

SYNOPSIS 

si rename [(--cpid ID|--changePackageId=ID)] 

[--[no|confirm]closeCP] [--[no]confirm] [--[no]defer] [-f] [--issueId=ID] 

[(--newName=value)] [--[no|confirm]overwrite] [--[no]renameWorkingFile] 





[(-g|--gui)] [--quiet] [--settingsUI=[gui|default]] [--status=[none|gui|default]] member... 

DESCRIPTION 

si rename renames an existing project member. This command only changes the basename of 

the member and cannot be used to move the member into a different directory or project. To move 

members, use the si move command. 

Options 



Before using si rename, note the following: 

❍ You can only rename members within a directory. You cannot rename a member and move 

it to a different directory or project. 

❍ Renaming a locked revision in a variant project moves the lock to the duplicate revision, 

even if the lock exists in the master project. 

--cpid=ID 





❍ You must specify this option if TrackLocks is enabled, and/or it is mandatory to 

specify a change package. 



188 of 457










--[no]confirm 

controls whether to confirm the rename before proceeding. 

--[no]defer 

controls whether to delay the rename operation in the project until the deferred operation is 

submitted. The rename operation in the sandbox still takes place immediately. This option is 

valid only if you are performing the command from a sandbox. 

-f 

force the rename without confirmation. 

--issueId=ID 




package ID. This option can only be specified if the Integrity Manager Integration is enabled. 



--newName=value 

specifies the new name of the renamed member. 


controls whether to overwrite the target (new name) working file if it exists. Specifying 

--overwrite means always do it, --nooverwrite means never do it, and 

--confirmoverwrite means always ask before doing it. This option is valid only if you 

are performing the command from a sandbox. 

--[no]renameWorkingFile 

controls whether to rename the working file in the sandbox immediately. 

member... 

identifies a specific member. You can only specify one member at a time. 

DIAGNOSTICS 


189 of 457

PREFERENCES 



SEE ALSO 

Commands: 

si add, si closecp, si co, si cpissues, si createcp, si diff, si drop si 

edit, si lock, si move si mergebranch, si rlog, si unlock, si viewcps 



190 of 457

si report 

generates a project report 

SYNOPSIS 

si report [--basename=value] [(-P project|--project=project)] 

[(-S sandbox|--sandbox=sandbox)] [ --devpath=path] [--projectRevision =rev] 




[-F|--selectionFile=value] [--status=[none|gui|default]] 

DESCRIPTION 

si report generates a report for a project. Use of this command requires your MKS Source 

Integrity client to be running Microsoft Access (TM) on the Windows operating system. 

Reporter calculates a summary of the changes to a project and all its archives, then displays or 

prints the summary as text or, for some reports, as a graph. Customized reports, created using 

Microsoft Access, can also be produced. 

Reporter's data files (containing the results of its project or archive analysis) can be saved as text 

files that can be read by most database applications. Reporter generates: 

● changes introduced by individual authors 

● changes between the member revision and a revision with a particular label 

● changes between the member revision and any other revision 

● a list of locked members and the names of users who locked them 

● a list of revisions with a particular label or state 

● project member history (including revision descriptions) by file 

For more details on report types, see the Source Integrity Enterprise Edition User Guide. 

Options 



--basename=value 

Specifies the name of generated tables. If you do not specify --basename=value, si 

report launches MKS Source Integrity Reporter (if installed). 

191 of 457

Data Fields 

si report uses the following suffixes to indicate the contents of the table: 

.txp project information 

.txm member information 

.txa archive information 

.txr revision information 

.txs symbols 

.txx access information 

In the generated data files, the first line of each data file contains field names. 

The fields for the project information file (.txp) are: 

ProjId 

(integer) A unique identifier of a project (Primary Key) 

ProjName 

(string) The project path/name 

The fields for the member information file (.txm) are: 

ProjId 

(integer) A unique identifier for the project, can be used as a key. Taken from project info 

(Foreign Key - 1:M). 

MemberName 

(string) Member file path/name. 

MemberType 

(string) Valid values are: 

a archive 

other (only valid for projects imported from 

f 

older versions of Source Integrity Standard 

i sub-project 

Revision 

(string) Revision number of member (can be NULL). 

ArchId 

(integer) A unique identifier of the member file, may be an archive id or another project id 

192 of 457

(can be NULL). Can be used as a primary key. 

The fields for the project information file (.txa) are: 

ArchId 



ArchiveName 

(string) File path/name, only for archives. 

Head 

(string) Revision number of the head revision. 

Branch 

(string) Branch number of a default branch if one has been set by si archiveinfo –b. 

(can be NULL). 

NumLocks 

(integer) The number of locked revisions. 

Format 

(string) One of text, binary or auto-detect. 

Encrypted 

(integer) Set to 1 if the archive is encrypted. This option is not supported in Source Integrity 

Enterprise. 

Compressed 

(integer) Set to 1 if the archive is compressed. 

TotalRevs 

(integer) Total number of revisions in the archive. 

Branches 

(integer) Total number of branches in the archive. 

BranchRevs 

(integer) Total number of revisions on branches. 

Comment 

(string) Comment delimiter if set (can be NULL). This field is historical. 

Description 

(string) Text describing an archive. This text is entered when the archive is first created. 

The fields for the revision information file (.txr) are: 

ArchId 



RevNum 

(string) The revision number of this revision (unique per ArchId). 

Date 

(string) The date this revision was entered, in the format yyyy/mm/dd hh:mm:ss. 

Author 

193 of 457

(string) The author’s name (usually the author’s user ID). 

State 

(string) The state assigned to this revision; this is taken from state list items). 

LinesAdded 

(integer) The number of lines added by this revision; derived from delta information. 

LinesDeleted 

(integer) The number of lines deleted by this revision. 

Locker 

(string) The name of the user holding a lock on this revision (usually the user’s user ID) and 

the time when the revision was locked. 

LogMsg 

(string) Text description of the changes made by this revision as entered at check in. 

The fields for the symbol information file (.txs) are: 

ArchId 



RevNum 

(string) The revision number of a revision that has an associated symbolic label. The 

revision number may not be unique in a list. 

Symbol 

(string) The symbolic label. 

The fields for the access information file (.txx) are: 

ArchId 



UserId 

(string) Name (user ID) of user who is included in an access list (Source Integrity Standard 

only) for an archive. The archive and project ID numbers (ArchId and ProjId) are unique for 

any set of reports (though they may change from one use of report to another). They may be 

used as keys. 

DIAGNOSTICS 


PREFERENCES 


194 of 457


SEE ALSO 

Commands: 

si projectinfo , si projects, si viewproject, si viewprojecthistory 



195 of 457

si restoreproject 

restores a project to a particular revision 

SYNOPSIS 

si restoreproject [(-r rev|--revision=rev)] [(--reason=reason|--reasonFile=file)] 

[--devpath=path] [(-P project|--project=project)] [(-S sandbox|--sandbox=sandbox)] 





DESCRIPTION 

si restoreproject restores a project to a particular checkpoint. When you apply the si 

restoreproject command, Source Integrity recursively checkpoints the selected project, then 

modifies it to reflect the member list of the target checkpoint. Any further development then 

proceeds from the restored checkpoint. 

Restoring a project is useful when development must revert back to an earlier version and there 

are no plans to proceed from the current version of the project. Restoring a project is not an option 

when the goal is to test a particular version. The project is always checkpointed before and after 

the restore. 

Note the following: 

● The si restoreproject command can potentially restore and checkpoint dropped 

subprojects that existed at the target revision, even if they are not currently a member of the 

project. 

● Do not use the si restoreproject command to create a new development branch from 

a previously checkpointed project revision. For new development paths, you should instead 

create a new development path. 

● To restore a variant project to a specific project revision, the development path must exist in 

all subprojects referenced by the project revision. 

Options 



--reason=reason 

--reasonFile=file 

196 of 457

specifies the reason text to be associated with restoring the project, or specifies a file where 

text can be retrieved. 

Note: 

Reasons that include spaces must be enclosed by quotes. 

DIAGNOSTICS 


PREFERENCES 



SEE ALSO 

Commands: 

si checkpoint 



197 of 457

si resync 

updates a sandbox with the member revision 

SYNOPSIS 

si resync [--mergeType=[confirm|cancel|automatic|manual]] 

[--onMergeConflict=[confirm|cancel|mark|launchtool|highlight|error]] [--[no]byCP] 

[--[no]confirm] [--[no]confirmPopulateSparse] [--[no]includeDropped] 

[--[no|confirm]merge] [--[no|un]expand] [-f] [--[no|confirm]overwriteChanged] 

[--[no|confirm]overwriteIfPending] [--[no|confirm]overwriteDeferred] 

[--[no]overwriteUnchanged] [--[no]populate] [--[no]restoreTimestamp] 

[(-R|--[no|confirm]recurse)] [--filter=filteroptions] [(-S sandbox|--sandbox=sandbox)] 





current or dropped member/subproject... 

DESCRIPTION 

si resync compares the contents of project members with their corresponding working files in 

the sandbox and replaces the working file with an exact copy of the member revision, if differences 

are detected or if no working file exists. If the working file is writable, you are optionally prompted 

for confirmation before it is replaced. This command has no effect on working files that are identical 

to the member revision. 

Note: 

This command overwrites files, even ones that you have locked and that have changed 

since you last checked them out. Be certain of your response to any prompts indicating that 

the files will be overwritten - once replaced, you cannot get back your changes. 

The Resync By Change Package Option 

The Resync by CP (--[no]byCP) option is primarily a tool for developers. When you want to 

resynchronize files in your sandbox, you usually do so by choosing individual files and then using 

si resync command. However, if the files you are resynchronizing have changes that are linked 

to other files, the standard resync operation would not include those related files. To resynchronize 

all related files, you would have to manually search for all the changes associated with the change 

package on the member you are resynchronizing. 

The Resync by CP option automates this process by searching the change package specified on 

the member revision you are resynchronizing and then bringing the changes from the project to 

198 of 457

your sandbox. 

While the Resync CP option searches all files related to a selected change package, and all the 

change packages that may be associated with the related files, the Resync By CP option only 

processes the change packages associated with the member you are resynchronizing. 

How Does the Resync By CP Option Work? 

The functioning of Resync by CP is affected by the options you choose for si resynccp. For 

more information, see si resynccp. 

When Should I Use the Resync By CP Option? 

Developers should use Resync By CP when they want to ensure that they have all dependent 

changes associated with a member revision, even if these changes are contained in other files. For 

example, a developer needs to check out (locked) a file and modify it. The developer finds that 

other revisions have been checked in since the member was resynchronized in the sandbox. 

Because the sandbox is quite large and contains many unrelated changes, the developer does not 

want to perform a standard resynchronization. The Resync By CP option can be used in this 

situation. 

Options 



Note: 

If the working file of the member you are resyncing has been modified, Source Integrity asks 

you to confirm that you want to merge your modifications into the working file. 


specifies how you want to merge changes from the working file in your sandbox into the 

member revision. 


--mergeType=cancel cancels the selected merge type. 


Merge tool. 

Caution: While Source Integrity and MKS Visual Merge are capable of performing 



199 of 457

epository. 




Guide. 







investigate conflicts or edit difference blocks before finishing the merge. 


conflicts; all non-conflicting blocks will already have been applied. 


"". You are responsible for resolving merge conflicts before checking 

in the changes. 



--[no]byCP 

controls whether to cause Source Integrity to operate in change package mode. Source 

Integrity automatically searches the change package associated with the member and 

resynchronizes all member files contained in that change package. 

Note: 

If there are no revisions in the change package to resynchronize, a normal resync is 

performed. 

--[no]confirm 

controls whether to proceed without confirmation messages when working with a change 

package (applies only when change packages are enabled). 

--[no]confirmPopulateSparse 

controls whether to proceed without confirmation messages when populating a sparse 

sandbox. 

--[no]includeDropped 

200 of 457

controls whether to delete dropped members from your sandbox. 


controls whether to merge changes from the working file in your sandbox into the member 

revision. 

--merge means always do it. 

--nomerge means never do it. 

--confirmmerge means always ask before doing it. 

Note: By default, Source Integrity prompts you for the type of merge (manual or automatic) 

to perform and what action to take if a conflict is encountered. 





keywords are: 

$Author$ 

$CompanyInfo$ 

$Date$ 

$Header$ 

$Id$ 

$Locker$ 

$Log$ 

$Name$ 

$ProjectName$ 



$RCSfile$ 

$Revision$ 



$Source$ 

$State$ 

-f 

overwrites the working file if it has changed since it was last checked in. This is equivalent to 

specifying --overwriteChanged. 



201 of 457

--overwriteChanged means always do it. 

--nooverwriteChanged means never do it. 

--confirmoverwriteChanged means always ask before doing it. Specifying the --yes 

or --no options would have the same effect as the first two, but would further answer "yes" 

or "no" to all questions asked, not just this one. 

--[no|confirm]overwriteIfPending 

controls whether to overwrite the working file if there is a pending operation on the revision 

corresponding to the working file. 


controls whether to overwrite the working file if there is a deferred operation on the revision 

corresponding to the working file. 

--[no]overwriteUnchanged 

controls whether to overwrite files that have not been modified in the sandbox. This may be 

useful for forcing files to pick up new keyword expansions or timestamps even if their 

content has not changed. 

--[no]populate 

controls whether to populate the sandbox with a working file for the specified member. If you 

are working with a sparse sandbox (see si createsandbox), specifying --populate 

with this command overrides the default sparse sandbox behavior of removing working files. 


controls whether to restore the timestamp of the working file to the timestamp of the revision 

in the member history. 


identifies a specific member or subproject that currently exists in the project, or one that has 

been dropped from the project but still exists in the sandbox. Use spaces to specify more 

than one. If you specify a dropped member or subproject, and if you specify 

--includeDropped, this command deletes the corresponding working file. 

DIAGNOSTICS 

See the diagnosticsreference page for possible exit status values. 

PREFERENCES 



SEE ALSO 

202 of 457

Commands: 

si applycp, si ci, si co, si resynccp, si revert 



203 of 457

si resynccp 

merges change package members to a Source Integrity sandbox 

SYNOPSIS 

si resynccp [--allowOpenCP] [--[no]alreadyInProjectIsError] 

[--backFill=[cp|revision|error|skip|ask]] 

[--mergeType=[confirm|cancel|automatic|manual]] 

[--onMergeConflict=[confirm|cancel|mark|launchtool|highlight|error]] 

[--[no]confirm] [--[no|un]expand] [-f|--[no|confirm]overwriteChanged] 

[--[no]ignoreBranches] [--[no]ignoreServer] [--[no|confirm]merge] 

[--[no|confirm]mergeOnBranch] [--[no|confirm]createVariants] 

[--[no]otherProjectIsError] [(--propagationCP=value)] [(--resolutionCP=value)] 

[--[no]restoreTimestamp] [--[no]spanProjects] [--[no]useMaster] 

[--[no]verbose] [(-S sandbox|--sandbox=sandbox)] [--hostname=server] 




[--status=[none|gui|default]] [--[no]ignoreUpdateRevision] 


DESCRIPTION 

si resynccp merges change package members to a Source Integrity sandbox. 

Feature Overview 

A change package specifies groups of members that are affected by an issue. An issue tracks 

changes that occur during the development process. An example of a change package would be a 

group of files that need to be changed to address a problem in program code. 

Both Apply CP and Resync CP rely on the use of change packages to track individual changes that 

modify project content or create new content. If a development team has been using change 

packages consistently, Source Integrity can isolate all changes related to a specific issue because 

this information is recorded as part of the change package. Once the dependencies are calculated, 

the operation completes and the change packages are applied in the project. 

If a development team does not use the change package methodology, isolating specific content 

becomes a complex, manual task. In a large code project, this could mean searching hundreds of 

files to determine which ones are related to a specific issue. To build the project, it would then be 

necessary to add, drop, rename, and move files, update file revisions, merge around unwanted 

revisions, merge in required changes, and merge out any unwanted changes. 

204 of 457


automated. In Source Integrity, the Apply CP operation adds, drops, renames, and moves files, 

and updates file revisions as required to create the desired change. If merging is required or other 

changes are needed to propogate the desired changes into the target project, you can use the 

Resync CP command. Resync CP allows you to either merge in desired changes or merge around 

unwanted changes. 

Apply CP and Resync CP are most useful for code and other text files where differencing can be 

performed. The operations are not recommended for binary files because of the difficulties 

encountered in differencing and merging binaries. 

The Change Package Methodology 

When used across a development project, Apply CP and Resync CP are powerful tools for 

managing changes and new content. However, the effectiveness of the functionality ultimately 

relies on the following factors: 

● accurate and consistent logging of issues into the Integrity Manager database 

● associating related changes into a single change package that ultimately addresses the 

issue in question 

Because issues, and their associated change packages, follow a workflow progression, it is critical 

that each member of the development team record and track all changes as they are made, from 

the initial phase to the completion phase in which the associated problem is addressed. All 

changes relating to a given issue must then be associated with the correct change package. Once 

the problem is addressed, or the feature added, that change package can be closed. 

It is equally important that issues are clearly delineated so that each change package addresses 

only one problem area or feature. Certainly, one problem area or feature may require many files to 

address it, but if you create a change package that is too wide in scope, it becomes difficult to 

extract specific changes later on. 

With accurate and consistent logging, Source Integrity can clearly identify the specific member 

revisions (or files) that address the identified problem or complete the required feature. Without this 

type of tracking, applying a change package may not have the desired results and manual reviews 

may become necessary. 

The Commands 

Consider the following scenario at abcBusiness--a major customer purchased version 2.0 of 

abcBusiness' Aurora software. The customer now wants a new feature--data compression--that 

they can use with Aurora 2.0 The development team at abcBusiness has already completed work 

on a data compression feature, bu the feature has been engineered only as part of the upcoming 

Aurora 3.0 release. 

205 of 457

To address the customer's needs, abcBusiness would normally have to assign a separate 

development team to create the new feature for Aurora 2.0 But how can abcBusiness take 

advantage of the work already completed on the data compression feature and provide it to the 

customer? 

If the development team has been using change packages, they can isolate the files that relate to 

the new data compression feature. However, without the functionality of Apply CP and Resync CP, 

the buildmaster at abcBusiness would have to manually search the required change package(s) 

and individually review all of the associated files to isolate the changes related to the feature. The 

buildmaster would then have to manually add, drop, rename, and move files, update file revisions, 

merge around unwanted revisions, merge in required changes, and merge out any unwanted 

changes. 


automated. In Source Integrity, the Apply CP operation works directly in the project to add, drop, 

rename, and move files, and update file revisions as required to create the desired change. Source 

Integrity presents you with a list--the backfill list--of all change packages required to capture the 

issue. In the Apply CP operation, you must either accept or decline this list--you cannot make 

selections. If you accept the list, the Apply CP command completes. If you decline the list, the 

Apply CP command cannot complete. 

If the Apply CP command fails because merging is required, you can then run the Resync CP 

command. Resync CP works in a sandbox and allows you to make selections from the backfill list. 

Source Integrity then merges around unwanted changes and uses differencing to merge files. 

Consider once again, the abcBusiness development team. Because the team has been tracking all 

of their changes through the use of change packages, they can target the main trunk of 

development and use Apply CP and Resync CP functionality to extract only those files that relate 

to the new data compression feature. Those specific change packages can then be applied to a 

variant project of Aurora 2.0 and testing carried out within a new project designed specifically for 

the customer. 

The functionality allows you to maximize existing development work, while being more responsive 

to both internal and external stakeholders. Apply CP and Resync CP are especially effective in any 

environment where there are large numbers of files to deal with--whether these are code files for a 

software project or Web pages for a complex Web site. 

Using Resync CP and Resync By CP 

This section provides an example to show how Resync CP can be used in your environment. The 

example also illustrates how Resync By CP can be used in a developer's sandbox. 

The development team at abcBusiness is working on the next release, which contains hundreds of 

206 of 457

files that span many Source Integrity projects. Whenever a fix is made, or a feature added, it may 

require the manipulation of a single file, or many different files across multiple projects. A fix or new 

feature may also include new dependencies within the source code. 

If developers resynchronize only a single file into their sandboxes, their builds may break because 

of new dependencies in the code. Such broken builds cause delays and prevent the team from 

completing their work on time. However, it is possible to avoid this lost time by using the Resync 

CP and Resync By CP commands. 

Resync CP and Resync By CP allow developers to specify a change package and have all 

changes associated with that change package resynchronized into their sandboxes. The 

commands save development time because they: 

● automatically search for the required files 

● determine what other change packages the selection is dependant on (this is known as the 

backfill list) and also resynchronize those change packages into the sandbox 

If the developer is working on a file conflict, Resync CP and Resync By CP also merge new 

information into a file. The merge operation ensures that the sandbox is up-to-date and that no 

changes are lost. 

The Resync CP and Resync By CP commands also allow a developer to remove a bug fix or 

feature that is incomplete or not working. 

Resync Change Package Command 

While Apply CP works to either add, drop, rename, or move members, or update member 

revisions, you must accept the entire list of backfill entries or the command fails. In the Resync CP 

operation, you are able to select the individual files you want to exclude from the backfill operation 

and then Source Integrity performs the required merges. Therefore, if you need to merge files to 

create your solution or make other changes to incorporate the desired change packages into the 

target project, you must use the Resync CP command. 

The Resync CP operation allows you resynchronize revisions and carry out merges entirely within 

a sandbox. When you are prompted to backfill historical revisions (the Resync CP backfill list), you 

can select the files you want to include. Resync CP automatically performs merging and notifies 

you of unresolved conflicts that must be addressed manually after the command completes. 

How Does Resync CP Work? 

Unlike the Apply CP command, you can undo the effect of a Resync CP operation by 

resynchronizing the sandbox again and then unlocking all locks. Because the master project has 

not been changed, the sandbox is restored to the state it was in prior to the Resync CP operation. 

207 of 457

Once the dependencies are calculated, and you have performed the required merges, the 

operation completes and Source Integrity presents all the files required for the new feature or 

content in your sandbox. 

When Should I Use Resync CP? 

You should use the Resync CP command when the Apply CP operation has failed because there 

were conflicts to be resolved through merging or if there are additional changes that need to be 

made in order to incorporate the change packages into the target project. Resync CP is most 

useful for developing software features and for applying bug fixes during the software development 

process. 

Note: 

When working in your sandbox, you can also use the Resynchronize By CP command. 

When you select a member and use Resynchronize By CP, Source Integrity automatically 

searches the change package associated with the member and resynchronizes the selected 

member and all other member files contained in that change package. For more information, 

see si resync. 

If the issues you are looking at have numerous associated change packages, you can also use a 

single change package--a resolution change package--that contains all the associated change 

packages, to resolve it. The Resync CP command includes a process for creating resolution 

change packages that can be used for this purpose. 

Note: 

If you attempt to perform a Resync CP command on a member that was previously dropped 

from a project, Source Integrity instructs you to manually re-add the member. 

Resolution Change Packages 

There are instances when the Apply CP command does not work on a set of change packages 

because merging is required. When this happens, the Resync CP command must be used to 

automate the required merging. Once the Resync CP operation is completed, the modified files 

that result from those merges are transferred to your sandbox. To apply the changes, you must 

then check in those modified files. 

For a development team using the change package methodology, the check in of the modified files 

requires an associated issue and change package. Once the issue has been created, the files can 

then be checked into the associated change package and the development path updated with the 

merged files. 

If other developers want to apply the same set of change packages, how can they be certain that 

the changes made relate only to the target feature and that no other changes have been checked 

in? To be absolutely certain, they would have to repeat the original Resync CP operation--a 

208 of 457

significant duplication of effort. Otherwise, they would have to resynchronize using the original set 

of change packages and possibly accept additional, unwanted changes that were selected during 

the first Resync CP operation. 

To avoid this uncertainty and duplication of effort, there is a mechanism for recording all change 

packages that have been applied, including the merge conflicts that have been resolved. The 

resolution change package is the mechanism for recording these changes. The resolution change 

package records all applied change packages, resolved conflicts, checked in modified files, and 

conflicts resolved by merging. 

In addition, you can only apply one resolution change package during each Apply CP operation, 

and if you select a resolution change package, you cannot apply any other change packages 

during that operation. Therefore, the applied changes are strictly limited and defined. Anyone 

wanting a specific set of changes can then select the associated resolution change package, run 

the Apply CP command, and obtain the same results. 

What Is a Resolution Change Package? 

A resolution change package is similar to a normal change package except that it contains 

additional information on: 

● change packages that have been applied 

● modified files that have been checked in 

● conflicts that have been addressed by merging 

When Should I Use a Resolution Change Package? 

You need to use a resolution change package if an Apply CP operation has failed because 

merging is required and you want to record the all merge operations required to address the issue. 

To accurately record all the results of the required merge operations, you should use a resolution 


Resolution change packages are particularly useful for assisting buildmasters to complete their 

work. When an Apply CP operation has failed, developers can identify the dependencies and 

required merges, and include all the necessary changes in a single resolution change package. 

The buildmaster can then redo the Apply CP operation using that resolution change package. This 

reduces the amount of decision-making required of the buildmaster and allows developers to 

resolve the conflicts in their own files. 

How Is a Resolution Change Package Created? 

A resolution change package is created only through the Resync CP operation. Using the graphical 

user interface, you can select an existing change package--or create a new one--and then ask 

Source Integrity to use this as a resolution change package. The only requirement is that the 

change package must be in the Open state. 

209 of 457

The change package you ask Source Integrity to use may or may not contain entries (that is, files), 

but for the greatest level of control in isolating a feature or issue, it is preferable to start with an 

empty change package. 

The process for creating a resolution change package is as follows: 

1. You create a normal change package and, during a Resync CP operation, you ask Source 

Integrity to use it as a resolution change package for recording all conflicts. 

2. Source Integrity takes the specified change package and adds a resolution list, thereby 

making it into a resolution change package. 

3. Once all the merge conflicts are addressed, you can check in the changes to the newly 

created resolution change package. 

4. After all the changes are checked in, you can then close the resolution change package, just 

as you would do for a normal change package. 

5. Apply the change package. 

Note: If reviews are mandatory, you must submit the resolution change package (you cannot close 

it manually). Submitting the resolution change package causes Source Integrity to apply the 

change package using the si applyCP command. If reviews are mandatory, the apply CP 

command records the applied changes in another change package that then follows the review 

process 

Are There Any Limitations When Using a Resolution CP? 

To avoid the problem of overlaps and conflicts during the Apply CP operation, you can only apply 

one resolution change package per operation. 

For more detailed information and examples on si resynccp and resolution change packages, 

see Applying Change Packages in the Source Integrity Enterprise User Guide. 

Propagation Change Packages 

During an Apply CP operation, your review of the changes you want to apply to a project may 

reveal potential merge conflicts or conflicts from files that have been added, dropped, renamed, or 

moved. For example, if a member has been removed from the source project, the Apply CP 

process re-adds the member to the project you are updating, creating an undesirable structural 

conflict. 

Resolving structural conflicts call for a propagation change package. Similar to a resolution change 

package, a propagation change package is initially constructed and populated using the Resync 

CP operation with deferred operations for members that need to be updated. Once the propagation 

change package is created, any conflicting entries can be discarded or corrected as needed prior 

to submission. As an alternative to a resolution change package, a propagation change package 

210 of 457

can also be used to resolve merge conflicts. 

Because a propagation change package records all the changes that need to be propagated 

between development paths, it is useful when incremental and repeated use of the Resync CP 

command is used to collect project changes. 

What is a Propagation Change Package? 

Technically, a propagation change package is a normal change package used to propagate 

specific changes from one development path to another. Conceptually, a propagation change 

package is a change package used to record and resolve changes that need to be applied 

between development paths. Similar to a resolution change package, a propagation change 

package records the changes that need to be made to resolve a merge. Unlike a resolution change 

package, a propagation change package records member changes and can be used across other 

development paths like a normal change package after it has been submitted. 

When Should I Use a Propagation Change Package? 

You need to use a propagation change package if an Apply CP operation includes undesirable 

member changes. You can use the Resync CP command to populate the propagation change 

package with the undesirable member changes in the form of deferred member operations. The 

undesirable member changes can then be discarded from the propagation change package prior to 

submission. 

Rather than perform one large Apply CP or Resync CP operation that can take a long time, a 

propagation change package allows you to incrementally propagate changes between 

development paths. Once the propagation change package is submitted, it records the changes 

made to the project. 

Options 



--allowOpenCP 

allows Source Integrity to apply open change packages. 

--[no]alreadyInProjectIsError 

Causes Source Integrity to terminate the operation if the member being resynchronized is 

the same one listed in the change package and is already in the project. If this setting is 

negated --noalreadyInProjectIsError, then the information is displayed as a 

warning. 

--backFill=[cp|revision|error|skip|ask] 

Specifies the way Source Integrity treats historic revisions required by the specified change 

package. For example, --backfill=ask means Source Integrity asks you to specify the 

change packages you want to exclude from the operation. 

211 of 457

The available values for the --backFill option include: 

--backFill=cp 

recursively chooses all historic revisions required by the specified change packages 

and applies them by updating member revisions, adding files, or dropping files. 

--backFill=revision 

processes only the specified change package(s) and chooses only directly associated 

revisions. It does not process any change packages that are associated with 

intermediate revisions. 

--backFill=error 

terminates the operation if other change packages are required but are not specified. 

--backFill=skip 

causes Source Integrity to merge around specified backfill revisions. Because the 

Apply CP command does not perform merging, this is treated as an error in Apply 

CP, allowed in Resync CP. 

--backFill=ask 

allows you to specify the change packages you want to include. 

--[no]ignoreUpdateRevision 

ignores update revision change package entries when performing the command. The default 

is to include update revision entries. 


specifies how you want to merge changes from the working file in your sandbox into the 

member revision. 


--mergeType=cancel cancels the merge. 


Merge tool. 

Caution: While Source Integrity and MKS Visual Merge are capable of performing 



repository. 




Guide. 


212 of 457






investigate conflicts or edit difference blocks before finishing the merge. 




"". You are responsible for resolving conflicts in the working file. 



--[no]confirm 

Confirm the actions before starting them. 


specifies whether Source Integrity should expand, unexpand, or ignore keywords when 

checking out working files. 

-f 


forces overwrite of changed working files. 

--[no|confirm]createVariants 

controls whether to confirm the creation of variant projects as needed. 

--[no]ignoreBranches 

Causes Source Integrity to use the most recent revision when it encounters two revisions of 

the same member on two development paths in the change package being applied. 

--[no]ignoreServer 

Causes Source Integrity to perform the Apply CP operation even if the change package 

members reside on different servers. 


controls whether to confirm all merge operations before completing them. 

--[no|confirm]mergeOnBranch 

controls whether to cause Source Integrity to perform a merge if the target revision is on a 

branch. Source Integrity differences the two file revisions and merges any changes into the 

213 of 457

working file without modifying its revision number. You must then check in the working file to 

advance the revision to the next available revision number. 

--[no]otherProjectIsError 

Causes Source Integrity to terminate the command if the member is in another project, for 

example, if the change package contains multiple entries in different top level projects. 

Change package entries referring to other projects are therefore treated as an error. 

--resolutionCP=value 

causes Source Integrity to lock merged working files under this change package (where 

value is the change package ID number). For example, specifying 

--resolutionCP=1285:2 would cause Source Integrity to lock all working files merged 

under change package 1285:2. 

--propagationCP=value 

specifies whether to create a propagation change package that is detached from the set of 

change packages it resolves (where value is the change package ID number). All the 

required operations are automatically represented as deferred entries. You can then discard 

entries that you do not want represented in the final application of changes to the project. 

Similar to resolution change packages, you can also add or change entries in the 

propagation change package as required. 


controls whether to restore the timestamp of the working file to the timestamp of the revision 

in the member history. If this is not specified, the timestamp is set to the current date and 

time. 

--[no]spanProjects 

Causes Source Integrity to apply the command to any member specified in the change 

package, even if this involves multiple projects. This option also applies across all 

sandboxes and results in a search of local sandboxes for all entries in the change package. 

--[no]useMaster 

causes Source Integrity to operate on the top-level sandbox. 

--[no]verbose 

Means Source Integrity includes additional information to track the current state of the 


issue... 


specifies the identification numbers for the change package you want to apply. For example, 

11804:2. 

DIAGNOSTICS 


PREFERENCES 


214 of 457


SEE ALSO 

Commands: 

si applycp, si resync 



215 of 457

si revert 

overwrites a sandbox file with a fresh copy of the working file, discarding changes 

SYNOPSIS 

si revert 

[--[no|un]expand] [-f] [--[no|confirm]overwriteChanged] [--[no|confirm]overwriteDeferred] [-- 

[no]overwriteUnchanged] [--[no]restoreTimestamp] [(-R|--[no|confirm]recurse)] [-filter=filteroptions] 

[(-S sandbox|--sandbox=sandbox)] [--hostname=server] [--port=number] [-password=password] 

[--user=name] [(-?|--usage)] [(-F file|--selectionFile=file)] [(-N|--no)] [(-Y|--yes)] [-- 

[no]batch] [--cwd=directory] [--forceConfirm=[yes|no]] [(-g|--gui)] [--quiet] [--settingsUI=[gui|default]] [-status=[none|gui|default]] 


DESCRIPTION 

si revert restores a working file to a state before changes were made, by overwriting the sandbox file with a fresh 

copy of the working file at the same revision you currently have in your sandbox, not the member revision. If you had the 

member locked, it is unlocked. 

Options 




controls whether to expand, unexpand, or ignore keywords in the member file. Keyword expansion is only 

available in text archives, not binary archives. For descriptions of the MKS Source Integrity keywords, see the 

Source Integrity Enterprise User Guide. Possible keywords are: 

$Author$ 

$CompanyInfo$ 

$Date$ 

$Header$ 

$Id$ 

$Locker$ 

$Log$ 

$Name$ 

$ProjectName$ 



$RCSfile$ 

$Revision$ 



$Source$ 

$State$ 

-f 

overwrites the working file if it has changed since it was last checked in. This is equivalent to specifying 

--overwriteChanged. 



216 of 457

--overwriteChanged means always do it 

--nooverwriteChanged means never do it 

--confirmoverwriteChanged means always ask before doing it. Specifying the --yes or --no options would 

have the same effect as the first two, but would further answer "yes" or "no" to all questions asked, not just this 

one. 


controls whether to overwrite the working file if there is a deferred operation on the member. 

--[no]overwriteUnchanged 

controls whether to overwrite files that have not been modified in the sandbox. This may be useful for forcing files 

to pick up new keyword expansions or timestamps even if their content has not changed. 


controls whether to restore the timestamp of the working file to the timestamp of the revision in the member 

history. 



DIAGNOSTICS 


PREFERENCES 


SEE ALSO 

Commands: 

si ci, si co, si resync 



217 of 457

si revisioninfo 

displays revision information 

SYNOPSIS 

si revisioninfo [--[no]changePackage] [--[no]labels] [(-r rev|--revision=rev)] 






DESCRIPTION 

si revisioninfo displays revision information for a member, for example: 

Options 



Revision: 1.7 

Created By: pmolinas on Jul 11, 2004 - 11:36 AM 

State: state_a 

Revision Description: 

Updated for Technical Review 

Labels: 

TechReview1 



--[no]changePackage 

controls whether to display change package information (applies only when change 

packages are enabled). 

--[no]labels 

controls whether to display member labels. 

member... 


DIAGNOSTICS 


218 of 457

PREFERENCES 



SEE ALSO 

Commands: 

si archiveinfo, si memberinfo, si mods, si rlog 



219 of 457

si rlog 

displays the revision log 

SYNOPSIS 

si rlog [--format=value] [--headerFormat=value] [--noFormat] [--noHeaderFormat] 

[--noTrailerFormat] [(-r rev|--revision=rev)] [--range=value] 


[--width=value] [-x value] [-y value] [(-R |--[no|confirm]recurse)] 



[--password=password] [--user=name] [--[no]persist] [--cwd=directory] 

[(-F file|--selectionFile=file)] [--forceConfirm=[yes|no]] [(-N|--no)] [--[no]batch] 

[--quiet] [(-?|--usage )] [(-Y|--yes)] member... 

DESCRIPTION 

si rlog displays the revision log and general archive information for every revision in a member 

history. The formatting is, by default, suitable for user viewing but it is also programmable, suitable 

for use in scripts. See the --format=value option description below. 

Options 



For a member, first the --headerFormat is processed. Then each revision is processed and 

formatted using the --fields or --format option. Finally, the --trailerFormat is processed. 

All three sections have available the global archive information. For each revision, the fields 

designated as per-revision are shown. 

--format=value 

defines an output format for user-formatted text. The default formatting is suitable for 

interpretation by most users; the various formatting options are provided for programmatic 

control. 

This option and the --fields option are mutually exclusive. 

--format options use the same values as --fields, but similar to a JAVA 

MessageFormat string (that is, it requires { } to surround each field). The --fields option 

automatically adds a newline on the end, but you must supply the newline for formats with a 

\n, for example: 

220 of 457

si rlog --format="{membername},{revision}\n" 

--headerFormat=value 

defines the header to be used. 

--noFormat 

disables formatting for user-formatted text. If --noFormat is specified, the per-revision 

iteration is not performed. 

--noHeaderFormat 

disables the header formatting. 

--noTrailerFormat 

disables the trailer formatting. 

--range=value 

specifies a range of revision numbers. The format of value for a single revision is simply the 

revision number itself. Separate multiple non sequential revisions with a comma, and use a 

dash to indicate a sequential range, for example, 1.2-1.5. 

You may also prefix or append a dash to a single revision number, meaning you want to 

show from 1.1 to the specified revision, or from the specified revision to the tip. For example, 

you would specify -1.6 to show revisions 1.1 to 1.6. Or you could specify 1.2- to show 

revisions 1.2 to the tip revision, whatever it may be. 

Another alternative is to use ?locker[:user] to match revisions that are locked, or locked by a 

certain user. For example, 

si rlog --noHeaderFormat --noTrailerFormat --range=?locker -format="{membername},{locker},{revision}\n" 

displays one line per locked revision, containing the membername, locker, and the revision 

locked. 

The revisions are printed in order from the highest revision to the lowest. 

--trailerFormat=value 

defines the trailer to be used. 






This option and the --format option are mutually exclusive. 


221 of 457

added 

per revision: the number of lines/bytes added for the current revision. 

alllabels 

global: all labels on any revision of the member, in the format 

label:revision[,label:revision]... 

alllockers 

global: user identifiers of all those who have locked revisions, in the format 

user:revision[,user:revision]... 

archivedescription 

global: the archive description. 

archivename 

global: the name of the archive to which the member refers. 

archiveshared 

global: indicators for members that share another member's archive; 1 if shared, 0 if 

not shared. 

attributes 

global: member attributes in the form attr=value[,attr=value]. 

author 

per revision: author of the revision. 

branchcount 

global: number of branches. 

branchid 

global: default branch. 

branchtiprev 

global: tip of the branch on which the member revision is located. 

compressed 

global: 1 if archive is stored compressed, otherwise 0. 

cpid 

per revision: the associated change package identifier (applies only when change 


cpsummary 

per revision: the associated change package summary (applies only when change 


date 

per revision: date on the revision. 

deleted 

per revision: the number of lines/bytes deleted on the current revision. 

description 

per revision: the revision description. 

format 

global: the storage format; 1 if stored as text, 0 if stored in binary format. 

formattedlabels 

global: all labels formatted into 80 column lines. 

frozen 

global: indicators for frozen members; 1 if frozen, or 0 if not frozen. 

222 of 457

haslabels 

global: 1 if alllabels is non-null, 0 if null. 

per revision: 1 if labels is non-null, 0 if null. 

haslocker 

per revision: 1 if locker is non-null, 0 if null. 

hasnewrevdelta 

global: displays 1 if the member revision is not on a tip. 

haspackage 

per revision: displays 1 if cpid is set, indicating the presence of a change package. 

headrev 

global: displays the head revision number. 

issandbox 

global: displays 1 if it is a sandbox, 0 if a project. 

labels 

per revision: a comma separated list of labels on this revision. 

lockdevpath 

per revision: displays the name of the development path where the lock on the 

revision was made from. This information is relevant when the locking policy is set to 

devpath, allowing a single user to have a single lock on an archive per development 

path. Contact your administrator for more information. 

locker 

per revision: the user ID of the user with this revision locked, or null. 

lockhost 

per revision: displays the host name of the computer that locked the member. 

lockproject 

per revision: displays the name and path of the project where the member revision 

was locked from. If the member revision was locked from a shared subproject, it is 

the original project's name and path that are displayed. 

locksandbox 

per revision: displays the name of the sandbox where the lock on the revision was 

made, and is relevant when viewing the information from the Locker Host. 

locktimestamp 

per revision: when locked, displays the time stamp for when the member was locked, 

otherwise null. 

memberdevbranch 

global: displays the member's development branch. 

membername 

global: displays the name of the member. 

memberrev 

global: displays the member revision number. 

223 of 457

memberrule 

global: displays the member rule on one line (in the header, if it exists). 

projectname 

global: from a project, displays the name of the project or subproject that the member 

belongs to. From a sandbox, displays the name of the sandbox or subsandbox that 

the member belongs to. 

projecttype 

global: displays 1 if the project is a regular project, 2 if the project is a build project, 3 

if the project is a variant project. 

rawmemberrule 

global: displays the member rule using the CLI syntax (in the header section, if it 

exists). 

relativemembername 

global: displays the member name relative to the top level project. 

revision 

per revision: revision number. 

revisioncount 

global: displays the count of the revisions. 

revisionsonbranchcount 

global: the number of revisions on branches. 

state 

per revision: displays the state. 

storageformat 

global: displays 1 if stored by reference, 0 if stored by delta. 

strictlocked 

global: displays an indicator for strictlocked members; 1 if strictlocked, otherwise 0. 

trunktip 

global: displays the trunk tip revision number. 

type 

global: always 0 to indicate a normal file member. 

workingarchive 

global: displays the name of the archive from which the working file is derived . 

NOTE: In the case where the working file was derived from an archive that was 

based on a server-side system setup (i.e. based on some default RCSPath or 

WorkToArch setting, as opposed to an explicit archive= reference), the 

workingarchive field displays the value "(default:)". The 

actual name of the archive from which the working file was derived can then be 

determined from the value for the archivename field. 

workingfile 

global: displays the working file name; null in a project. 

workingfileexists 

global: displays 1 if a sandbox and working file exists, 0 if operating on a project. 

workingfilerevunknown 

global: displays 1 in a sandbox if the working revision is unknown, or 0 if known. 

224 of 457

Always displays 0 in a project. 

workingrevdelta 

global: displays 1 in a sandbox if the working revision is the same as the member 

revision, or displays 0 in a project. 

workingfilewritable 

global: displays 1 if a sandbox and working file are writable. 

workingrev 

global: displays the working revision. 


used with the -g or --gui options, specifies the height of the print view window, in pixels; 

value must be a whole number. 

--width=value 

used with the -g or --gui options, specifies the width of the print view window, in pixels; 


-x value 


-y value 


--[no]persist 




member... 


DIAGNOSTICS 


PREFERENCES 



SEE ALSO 

Commands: 

si archiveinfo, si diff, si memberinfo, si mods, si print, si projectinfo, 

si report, si revisioninfo, si sandboxinfo, si viewhistory 


225 of 457


226 of 457

si sandboxes 

lists sandboxes on the client 

SYNOPSIS 

si sandboxes [--[no]displaySubs] [--height=value] [--manage] [--width=value] 

[-x value] [-y value] [(-?|--usage)] [(-N|--no)] [(-Y|--yes)] [--[no]batch] [--cwd=directory] 

[--forceConfirm=[yes|no]] [(-g|--gui)] [--[no]persist] [--quiet] 

[--settingsUI=[gui|default]] [-F|--selectionFile=value] [--status=[none|gui|default]] 

DESCRIPTION 

si sandboxes displays sandboxes currently registered on the MKS Source Integrity client and 

the corresponding project, server name, and port number, for example: 

Options 

c:\demoapp\project.pj -> /projects/demoapp/project.pj 

(server.mks.com:7001) 



--[no]displaySubs 

controls whether to display subsandboxes. 


used with the -g or --gui options, specifies the height of the sandbox view window, in 


--manage 

enables the sandbox manager view for those using the -g or --gui options. 

--width=value 

used with the -g or --gui options, specifies the width of the sandbox view window, in 


-x value 


-y value 


--[no]persist 




227 of 457

DIAGNOSTICS 


PREFERENCES 



SEE ALSO 

Commands: 

si createsandbox, si dropsandbox, si importsandbox, si sandboxinfo, si 

viewsandbox 



228 of 457

si sandboxinfo 

lists information about a sandbox 

SYNOPSIS 

si sandboxinfo [--[no]attributes] [(-S sandbox|--sandbox=sandbox)] 





DESCRIPTION 

si sandboxinfo displays current information about a sandbox, for example: 

Options 

Sandbox Name: c:\SourceCode\project.pj 

Project Name: c:/master_projects/SourceCode/project.pj 

Server: intra-wif:7001 

Revision: 1.4 

Last Checkpoint: Feb 15, 2003 - 3:28 PM 

Members: 0 

Subsandboxes: 3 

Line Terminator: native 

Project Description: 

Project Attributes: none 

Sandbox Attributes: none 




controls whether to display project and sandbox attributes. 

DIAGNOSTICS 


PREFERENCES 

229 of 457



SEE ALSO 

Commands: 

si archiveinfo, si ci, si memberinfo, si mods, si projectinfo, si rlog, si 

sandboxes, si viewsandbox 



230 of 457

si servers 

displays the current connections to an Integrity Server 

SYNOPSIS 

si servers [--[no]showVersion] [--height=value] [--width=value] [-x value] [-y value] [(-?|--usage)] 

[(-N|--no)] [(-Y|--yes)] [--[no]batch] [--cwd=directory] [--forceConfirm=[yes|no]] [(-g|--gui)] 

[--[no]persist]] [--quiet] [-F|--selectionFile=value] [--settingsUI=[gui|default]] 


DESCRIPTION 

si servers displays active server connections in the format user@host_name:port. 

The default server connection is indicated by user@host_name:port(default). 

Options 



--[no]showVersion 

controls whether to show build version information for the connected server. The presentation of this 

information is in the format [Build: 2015]. 


used with the 

-g or --gui options, specifies the height of the servers view window, in pixels; value must be a whole number. 

--width=value 

used with the 

-g or --gui options, specifies the width of the servers view window, in pixels; value must be a whole number. 

-x value 


-y value 


--[no]persist 

controls whether this presentation of information should continue to be updated as new information becomes 

available. --nopersist forces a static "snapshot" of information, while --persist gives real-time updates. 

DIAGNOSTICS 


PREFERENCES 


SEE ALSO 

231 of 457

Commands: 

si connect, si disconnect 



232 of 457

si setmemberrule 

sets the member rule for one or more members 

SYNOPSIS 

si setmemberrule [--clear] [--[no]confirm] [--[no]expand] [-f] 

[--[no|confirm]overrideRule] [(-r rev|--revision=rev)] 







DESCRIPTION 

A member rule is a revision--typically a symbolic revision--attached to a member that you can use 

regularly to update the member’s revision or use it with any command that allows you to specify the 

member rule as a pre-defined revision. In the graphical user interface, only the Check Out and 

Update Member Revision commands allow you to specify a member rule. In the command line 

interface, any command that accepts the -r|--revision option allows you to specify a member 

rule. For example, you can check out a revision corresponding to the member rule in the graphical 

user interface or add a label to a revision corresponding to the member rule in the command line 

interface. After you create a rule for a member, you can also view the rule using the si 

memberinfo command. 

Important: By design, applying a rule as a member revision to a member does not dynamically 

update the member revision of the corresponding member in an external project configuration 

(normal, variant, build). For example, if member 1’s member revision is updated in project A, the 

corresponding member in a variant of project A with the rule configured to link to project A is not 

updated with the same member revision. To update the corresponding member in the variant 

according to the member rule, you must use the si updaterevision command with the 

member rule, or your administrator can configure the ClientLink.js sample event trigger script 

that enables dynamic updating of linked member revisions under certain conditions. For more 

information, contact your administrator. 

Example: 

1. A project administrator defines a rule based on a label and implements it: 

si setmemberrule -rReadyForUse demoapp.c demoapp.h 

233 of 457

si updaterevision -r:rule demoapp.c demoapp.h 

si freeze demoapp.c demoapp.h 

2. Developers work as usual, using :member. 

Note: In this scenario, it is not expected that members with the rule are modified locally. 

3. From time to time, the project administrator re-applies the rule, based on new revisions 

marked ReadyForUse: 

Options 

si thaw demoapp.c demoapp.h 

si updaterevision -r:rule demoapp.c demoapp.h 

si freeze demoapp.c demoapp.h 

Several rule filters are available so you can easily work with members that contain rules. For 

more information, see the --filter option in the options reference page. 



-r 

--revision 

revision to update the member revision to. For revision options, see options. 

--clear 

clears the member rule and removes it from the specified members. 

--[no]confirm 

causes Source Integrity to confirm that the rule will be cleared. 

--[no]expand 

controls whether to expand the revision before setting the rule. 

-f 

forces removal of the rule without confirmation. 

--[no|confirm]overrideRule 

controls whether to override the existing member rule. 

member... 


DIAGNOSTICS 


234 of 457

PREFERENCES 



SEE ALSO 

Commands: 

si ci, si co, si edit, si resync, si revert, si updatearchive, si 

updaterevision 



235 of 457

si setprefs 

sets preferences 

SYNOPSIS 

si setprefs [--command=value] [--[no]resetToDefault] [--[no]save] [--[no]ask] 

[--ui=[unspecified|gui|cli|api]] [(-?|--usage)] [(-F file|--selectionFile=file)] [(-N|--no)] 

[(-Y|--yes)] [--[no]batch] [--cwd=directory] [--forceConfirm=[yes|no]] pref[=value]... 

DESCRIPTION 

si setprefs sets preferences and configuration options. These settings are used to determine default 

behaviors for other commands - each option on each command has a preference key associated with it. 

The si viewprefs command lists the commands and preference keys. Changes to your preferences 

are either for the current client session (until si exit is used) or may be permanently saved in your 

system's home directory, into a file named IntegrityClient.rc, using the --save option. 

To permanently enable keyword expansion when checking in members, for example, you would specify: 

si setprefs --command=ci --save keywordExpand=expand 

Your administrator can also lock certain preferences from the Integrity Server, preventing you from 

configuring them using the si setprefs command. Preferences that are locked -- viewable with si 

viewprefs -- display (locked) at the end of the output line. The following preferences can be locked 

from the server by editing Source Integrity policies in the Administration Client: 

Tip: For information on editing Source Integrity policies, see "Configuring the Integrity Server" in the 

Integrity Server Administration Guide. 






onLock si co 


si resync, 

si resynccp, si revert 





236 of 457

Warning: Do not edit the IntegrityClient.rc file manually, because preferences that appear more 

than once in the IntegrityClient.rc file can cause Source Integrity to behave unpredictably. 

Options 

This command takes the universal options available to all si commands, as well as some general options. 

See the options reference page for descriptions. 

--command=value 

identifies the command to be set. For an easy way to see a list of commands and values that may 

be set, simply type the si viewprefs command, either piped through |more or redirected to a 

file, for example: 

si viewprefs --global --showValidValues >prefs.txt 

The commands and preference keys are also listed on the preferences reference page. 

--[no]resetToDefault 

controls whether to revert specified settings to the default values as shipped with MKS Source 

Integrity Client. If specifying --resetToDefault, you must not specify =value for each preference. 

--[no]save 

controls whether changes should be permanently saved. 

--[no]ask 

controls prompts to the user for specific preferences. Each preference option may be set to either -ask 

or --noask. When the command itself is run, any option set to --ask and that is not explicitly 

set with command line options will be queried. If this --ask option is set, then you do not specify a 

value for the preference at the same time, but instead the pref=value must supply one of the 

following four valid ask values: 

once 

never 

asks the user the first time only, and then uses the provided value every time after for the 

duration of that command. 

never asks the user for a response, but uses the current setting (which may be specified by a 

preference). 

element-last 

asks the user for each element of the selection, providing the most recently used value as the 

default. 

element-pref 

asks the user for each element of the selection, resetting the default to the value specified by 

the preference. 

For example, to set the server host for si connect to a specific host name, you specify something 

like: 

237 of 457

si setprefs --command=connect 

server.hostname=specific.hostname.com 

but to set the preference to ask for a host name when using si connect, you specify something like: 

si setprefs --command=connect --ask 

server.hostname=element-last 

--ui=[unspecified|gui|cli|api] 

controls whether to apply the preference to the graphical user interface, the command line interface, 

or when the interface is unspecified. By default, --ui=cli is implied when issuing the si 

setprefs. To set preferences for GUI behavior, however, you should specify --ui=gui. For 

example, to set the manage preference to be true in the GUI for the si sandboxes command, you 

would type: 

si setprefs --command=sandboxes --ui=gui manage=true 

These correlate to settings in the IntegrityClient.rc file, which can be seen as having the gui.si. or 

cli.si. prefix, or simply the si. prefix when it is unspecified. 

pref[=value]... 

identifies the preference string. If you specified the --resetToDefault option, then you only need 

to specify the preference name; otherwise specify a value for the preference. Use spaces to specify 

multiple preferences. 

DIAGNOSTICS 


PREFERENCES 



SEE ALSO 

Commands: 

si loadrc, si viewprefs 



238 of 457

si setprojectdescription 

sets the project description 

SYNOPSIS 

si setprojectdescription [--description=desc] [(-P project|--project=project)] 


[--port=number] [--password=password] [--user=name] [(-?|--usage)] [(-N|--no)] 


[--quiet] [--settingsUI=[gui|default]] [-F|--selectionFile=value] 


DESCRIPTION 

si setprojectdescription sets the one line description of a project. 

Options 




specifies the new description text to be set as the project description. 

Note: 


DIAGNOSTICS 


PREFERENCES 



SEE ALSO 

Commands: 

239 of 457

si addprojectlabel, si appendrevdesc, si checkpoint, si projectinfo, si 

viewproject, si viewprojecthistory 



240 of 457

si sharesubproject 

shares an existing subproject between multiple projects 

SYNOPSIS 

si sharesubproject [--sharedProject=project location] 

[-r subproject revision|--subprojectRevision=subproject revision] 


name] [--type=[normal|variant|build|default]] [(-P project|--project=project)] 

[(-S sandbox|--sandbox=sandbox)] [--devpath=development path name] [--hostname=server] 

[--port=number] [--password =password] [--user=name] [(-?|--usage)] [(-F file|--selectionFile=file)] 

[(-N|--no)] [(-Y|--yes)] [--[no]batch] [--cwd=directory] [--forceConfirm=[yes|no]] [(-g|--gui)] [--quiet] 

[--settingsUI=[gui|default]] [--status=[none|gui|default]] subproject location 

DESCRIPTION 

A shared subproject is a subproject that is a member of more than one project. Source Integrity allows you to share a 

subproject between two or more projects by referencing the original subproject. A shared subproject allows you to 

access common members across many projects. Shared subprojects are not required to be located within the same 

directory structure or project hierarchy. 

A shared subproject functions the same as an unshared subproject and is accessible by the same commands. 

Shared subprojects that were created in a previous version of Source Integrity (Standard Edition) are detected as 

they are accessed by Source Integrity Enterprise without disrupting the operation. The format of these subprojects is 

retained until you change or update it to the new format by re-configuring it. 

Options 



--sharedProject=project location 

specifies the path and name of the subproject you want to share, for example, 

c:/Libra_Program/project.pj. 

-r subproject revision 







--type=[normal|variant|build|default] 


--type=normal configures the subproject to the master (non-variant) version of the subproject. 



241 of 457










specifies the path and name of the project you want to add the shared subproject to, for example, 


subproject location 

specifies where in the project you want the shared subproject to appear, for example, 

c:/Aurora_Program/bin/Libra/. 

DIAGNOSTICS 


PREFERENCES 


SEE ALSO 

Commands: 

si addsubproject, si checkpoint, si configuresubproject, si createproject, si 

createsandbox, si createsubproject, si drop, si dropproject, si importproject, si 

projectinfo, si projects, si viewproject 



242 of 457

si snapshot 

records the state of a sandbox. 

SYNOPSIS 

si snapshot [--targetDevpath=value] [--author=value] [-d|--description=value] 

[--descriptionFile=snapshot] [-L|--label=value] [--[no]labelMembers] 

[--[no]notify] [-s|--state=value] [--[no]stateMembers] [-S|--sandbox=value] 





DESCRIPTION 

si snapshot records a capture of the current state of a sandbox, where each element in the 

sandbox can be identified with a pre-existing entity in the repository on the Integrity Server. The 

sandbox snapshot creates a standard project revision from which a build sandbox can be created 

and a development path assigned. The project revision number takes the form of a branched 

revision in the project history. For example, if the head revision of the project is 1.1, then the 

project revision created by the snapshot will be 1.1.1.1. 

Note: si snapshot records the state of a sandbox, while si checkpoint records the state of a 

project. Checkpointing is recommended for recording milestones during the development of a 

project; however, there may be situations where you may need to take a snapshot of a sandbox to 

record the state for later use. 

The state of a sandbox is defined by its set of elements, which include the following: 

● sandbox members identified with an archive and working revision from which the working 

file was created 

● former members that were dropped, but are still present in your sandbox 

● subsandboxes, identified by project name and type 

● former subsandboxes that were dropped but are still present in your sandbox 

Note the following about how si snapshot handles the set of sandbox elements: 

● To be included in the snapshot, all working files must be checked in. There must be no 

working file changes in the sandbox. 

● If the working file revision differs from the member revision, it is the working file revision that 

is included in the snapshot. 

● Members with no working files are not included in the snapshot. 

243 of 457

● Former members that still have working files in the sandbox directory appear as members in 

the snapshot. 

● Former subprojects that are still in the sandbox directory appear as restored subprojects in 

the snapshot. 

For more information on sandbox snapshots, see the Source Integrity Enterprise User Guide. 

Options 




specifies the development path to create the snapshot from. With this option you can only 

specify an existing development path. 

--author=value 

specifies the author of the snapshot revision. 

-d 

--description value 

specifies the description for the snapshot revision. 

--descriptionFile=value 

specifies a file containing the description for the snapshot revision. 

-L 

--label=value 

specifies a label for the snapshot revision. Note the following about using labels: 






--[no]labelMembers 

assigns the specified label to the working revisions. 

--[no]notify 

provides a notification when the snapshot has been created. 

-s 

--state=value 

specifies the state for the project revision created by the snapshot. 

--[no]stateMembers 

specifies whether to apply the state to all members or only the project. 

-S 

--sandbox=value 

specifies the name of the sandbox to snapshot. 

244 of 457

DIAGNOSTICS 


PREFERENCES 



SEE ALSO 

Commands: 


rlog, si sandboxinfo, si viewhistory, si viewlabels, si viewproject, si 

viewprojecthistory 



245 of 457

si submit 

submits a deferred operation 

SYNOPSIS 

si submit [(--cpid ID|--changePackageId=ID)] [--issueId=ID] 

[--[no|confirm]closeCP] [-f] [--[no]overrideCPID] [(-R|--[no|confirm]recurse)] 

[--filter=filteroptions] [--[no|confirm]recurse] [(-S sandbox|--sandbox=sandbox)] 


[(-?|--usage)] [-F value] [(-N|--no)] [(-Y|--yes)] [--[no]batch] [--cwd=value] 


[--status=[none|gui|default]] [-F|--selectionFile=value] sandbox member... 

DESCRIPTION 

si submit submits a deferred operation in your sandbox. Submitting the operation completes the 

command and makes it visible in the associated project. If reviews are mandatory, submitting a 

deferred operation creates a pending entry in the associated change package. 

Options 



--cpid=ID 















246 of 457


-f 

force all elements to be submitted with the specified change package ID override. 

--issueId=ID 







--[no]overrideCPID 

force all elements to be submitted with the specified change package ID override. 



DIAGNOSTICS 


PREFERENCES 



SEE ALSO 

Commands: 

si add, si ci, si drop, si move, si rename 



247 of 457

si submitcp 

submits a change package. 

SYNOPSIS 

si submitcp [--[no|confirm]closeCP] [--hostname=server] [--port=number] 




[--[no|confirm]commit] [--[no|confirm]deferredIsError] 

[--[no|confirm]ignoreNoDeferred] issue|issue:change package id... 

DESCRIPTION 

si submitcp submits the uncommitted operations in a change package. Although you can 

submit operations individually via si submit, you can ensure that no operations are missed by 

submitting a change package that contains deferred operations. Deferred operations are visible 

only from the Source Integrity Client, and are not committed to the project or repository until they 

are submitted. If reviews are mandatory, submitting the change package begins the review process 

(pending entries are created). 

When a change package is submitted, all of the deferred operations are submitted. Any locked 

members are converted to deferred check in operations and then checked in. 

When reviews are mandatory, submitting a change package begins the review process. Deferred 

entries become pending entries, and are committed to the server repository by Source Integrity 

once the change package has been accepted. For more information, see the Source Integrity 

Enterprise User Guide 

If the change package is a resolution change package, by default you are prompted with the option 

to apply the change package after it is submitted. 

Options 




specifies whether to close the change package after it has been submitted. 

--[no|confirm]commit 

specifies whether to commit deferred or pending changes to the server repository, or submit 

them for review. The default is to commit without confirmation. 

248 of 457

--[no|confirm]deferredIsError 

specifies whether to proceed with the submit operation if there are deferred change package 

entries. 

--[no|confirm]ignoreNoDeferred 

specifies whether to proceed with the submit operation if there are no deferred or lock 

change package entries. 

issue... 


issue identifies a specific issue that contains all open change packages that you want to 

close; use spaces to specify more than one issue. 

issue:change package id identifies a specific change package to close; use spaces to 


DIAGNOSTICS 


PREFERENCES 



SEE ALSO 

Commands: 

si acceptcp, si rejectcp, si closecp, si add, si ci, si co, si cpissues, si 

createcp, si drop, si viewcps, si viewcp. 



249 of 457

si thaw 

thaws a project member 

SYNOPSIS 

si thaw [(-R|--[no|confirm]recurse)] [--filter=filteroptions] 






DESCRIPTION 

si thaw thaws project members previously frozen with the si freeze command. Once thawed, 

all operations normally associated with a member can be performed again. 

Options 



member... 


DIAGNOSTICS 


PREFERENCES 



SEE ALSO 

Commands: 

si checkpoint, si freeze 

250 of 457



251 of 457

si unlock 

unlocks a member 

SYNOPSIS 

si unlock [--[no|confirm]breakLock] [(-r rev|--revision=rev)] 







DESCRIPTION 

si unlock unlocks a member. If you do not specify any members, si unlock applies to all 

members. By default, si unlock unlocks the member revision of each archived member. 

Options 



--[no|confirm]breakLock 

controls whether to break someone else's lock. If someone else has the member locked and 

you have the BreakLock permission (see ACL), you will normally be prompted to confirm 

whether you want to break their locks. 

member... 


DIAGNOSTICS 


PREFERENCES 



252 of 457

SEE ALSO 

Commands: 

si ci, si co, si edit, si lock, si rlog 



253 of 457

si unlockarchive 

unlocks a revision in an archive. 

SYNOPSIS 

si unlockarchive [--archive=value] [-r|--revision=value] [--hostname=server] 

[--port=number] [--password=password] [--user=name] [(-?|--usage)] [(-N|--no)] 


[--quiet] [--settingsUI=[gui|default]] [-F|--selectionFile=value] 


DESCRIPTION 

si unlockarchive unlocks a revision in an archive. You can use this command to unlock 

members that have been dropped from a project, and members locked in a project for which you 

longer have permission to view. 

Options 



--archive=value 

specifies the server side archive name. 

-r 


specifies the locked revision number. 

DIAGNOSTICS 


PREFERENCES 



SEE ALSO 

254 of 457

Commands: 






255 of 457

si updatearchive 

manipulates various member archive attributes 

SYNOPSIS 

si updatearchive [--archiveDescription=description] [--[no]compress] 

[--defaultBranch=value] [--storageFormat=[delta|reference]] [--[no]strictLock] 







DESCRIPTION 

si updatearchive manipulates various member archive attributes. 

Note: 

Options 

This command affects the base archive, and, therefore, all projects and development paths 

referring to the archive. 



--archiveDescription=description 

sets the archive description for a member. description is stored in the member's meta data 

as an archive description. If description has spaces then it must be enclosed by quotes. 

--[no]compress 

controls whether to compress the member's archive. This is recommended for use by the 

system administrator only. On WIN32/NT systems, use the NTFS built-in compression 

instead. 

--defaultBranch=value 

sets the default branch MKS Source Integrity uses to check in files. If unspecified, files are 

checked in to the trunk. 

--storageFormat=[delta|reference] 

identifies what type of format to use in the archive. This is recommended for use by the 

system ADMIN only. delta is the traditional Source Integrity reverse delta format, while 

reference means to store member history by reference -- each revision is stored as a 

separate file. Particularly for binary files, storing by reference can enhance performance. 

256 of 457

--[no]strictLock 

controls whether to set strict locking for the member. Without a strict locking policy, Source 

Integrity respects locks but does not require them. When --strictLock is specified, 

Source Integrity uses the file system's read-only attribute to assist in the locking process. If 

you do not lock a revision when you check it out, the working file based on that revision is 

read-only. 

member... 


DIAGNOSTICS 


PREFERENCES 



SEE ALSO 

Commands: 

si ci, si co, si createdevpath, si edit, si resync, si revert, si 

updaterevision 



257 of 457

si updateclient 

updates the Integrity Client with a Service Pack 

SYNOPSIS 

si updateclient [--[no|confirm]download] [--[no|confirm]shutdown] 



[--cwd=directory] [--forceConfirm=[yes|no]] 

DESCRIPTION 

si updateclient updates the Integrity Client with a Service Pack from the server if one is 

available. A Service Pack may be designated as required to address a known issue, or may 

provide enhancements. Client side Service Pack numbers are designated with a "C", for example, 

C04030003. 

Options 

This command takes the universal options available to some si commands, as well as some 

general options. See the options reference page for descriptions. 

--[no|confirm]download 

automatically downloads a Service Pack if one is available. 

--[no|confirm]shutdown 

automatically shutdowns the client if a Service Pack is downloaded. 

DIAGNOSTICS 


PREFERENCES 



SEE ALSO 

Commands: 

258 of 457

si connect, si disconnect 



259 of 457

si updaterevision 

updates a project member revision to a specific revision 

SYNOPSIS 

si updaterevision [--cpid|--changepackageID=value] [--[no|confirm]closeCP] 

[--[no]defer] [--issueID=value] [(-r rev|--revision=rev)] 






[--status=[none|gui|default]] [--[no]save] member... 

DESCRIPTION 

si updaterevision updates a member revision to a specific pre-existing revision. This is useful 

when you want the member revisions in a project to reflect revisions based on a symbolic location 

in the development path (working file, head revision, trunk tip, member branch tip), property (state, 

label, timestamp), current project configuration, or external project configuration. 

Note: You cannot update a frozen member’s revision. You must first thaw the member (si thaw) 

and then update it. 

Options 



-r 

--revision 

revision to update the member revision to. For revision options, see options. 

--[no]save 

Used to save any revision specified by -r (see options). Although existing saved revisions 

can be referenced using the :rule symbolic revision, this option has been deprecated in 

favor of the member rule. MKS recommends using the member rule instead of the -- 

[no]save option. For more information about the member rule, see si setmemberrule). 

--cpid=value 




260 of 457




❍ If you have TrackLocks enabled, Source Integrity prompts you with the change 

package you used when you checked out the specified member, not the default 

change package. From the graphical user interface, you must manually select the 









--[no]defer 

controls whether to delay the operation in the project until the deferred operation is 




member... 


DIAGNOSTICS 


PREFERENCES 



SEE ALSO 

Commands: 

si ci, si co, si edit, si resync, si revert, si updatearchive, si 

setmemberrule 



261 of 457

si viewcp 

displays a change package's details 

SYNOPSIS 

si viewcp [--fields=field1[:width1],field2[:width2]...] [--[no]showCommitted] 

[--[no]showUncommitted] [--[no]showPending] [--[no]showReviewLog] 

[--format=value] [--height=value] [--width=value] [-x value] [-y value] 

[--headerFormat=value] [--noFormat=value] [--noHeaderFormat=value] 

[--noTrailerFormat=value] [--trailerFormat=value] [--width=value] 



[--cwd=directory] [--forceConfirm=[yes|no]] [--quiet] [(-g|--gui)] 

[--settingsUI=[gui|default]] [--status=[none|gui|default]] issue|issue:change package id... 

DESCRIPTION 

si viewcp allows you to view details on any change package you select. You can select the 

change package using an issue ID or change package ID, and the change package does not have 

to be assigned to you. 

Options 






optional. Fields are separated with a space. 


archive 

displays the archive name of member in the change package entry. 

closeddate 

displays the date the change package was closed on. 

description 

displays the description of the selected change package. 

id 

displays the ID of the issue associated with the selected change package. 

isclosed 

262 of 457

indicates if the change package is closed. 

member 

displays the member names in the change package. 

project 

displays the project the change package is associated with. 

resolution 

indicates whether or not the selected change package is a resolution change 

package. 

resolutionlist 

displays the list of change packages resolved by a selected resolution change 

package (the resolution list is displayed by default if a resolution change package is 

selected). 

revision 

displays the member revision number. 

sandbox 

displays the name of the sandbox where the deferred operation or check out took 

place. 

server 

displays the server the change package resides on. 

siserver 

displays the Source Integrity server the change package resides on. 

state 

displays the status of the change package. 

summary 

displays the change package summary. 

timestamp 

displays the timestamp of the selected change package. 

type 

displays how the member was added to the change package: add, update, drop, lock, 

rename-to, or rename-from. 

user 

displays the ID of the user who added the member to the change package. 

variant 

displays the names of variant projects associated with the member. 

creationdate 

displays date the change package was created.. 

--[no]showCommitted 

specifies if to display committed operations. Committed operations appear as change 

package entries that contain changes committed to the server repository. 

--[no]showUncommitted 

specifies if to display uncommitted operations. Uncommitted operations are Lock or deferred 

entries that can be submitted to the server repository. 

--[no]showPending 

specifies if to display pending entries that have not yet committed to the repository. 

--[no]showReviewLog 

263 of 457

specifies if to display review information. Source Integrity provides review logs as part of a 

complete review audit process. A log consists of individual records for each reviewer vote 

cast. Each time the change package is submitted for review, a new log begins. 

Each review record contains the following information: 

Review States The possible review states are: 

❍ Review Pending the change package is still in a state of Submitted and there are 

outstanding votes to be cast by reviewers. 

❍ Accepted the change package is in a state of Accepted, and all of the individual 

reviewers and a user from each reviewer group have accepted the change package. 

❍ Rejected the change package is in a state of Rejected, and at least one reviewer has 

rejected the change package. 

Reviewer Type The possible reviewer types are: 

❍ User Reviewer is a user voting in an individual capacity. 

❍ Group Reviewer is a user voting in a group capacity on behalf of that group. 

❍ Super Reviewer is a user casting an overriding vote in a super reviewer capacity, 

and is not required to be a user on the reviewer list or in a group on the group 

reviewer list. 

Votes The possible vote values are: 

❍ Pending signifies that the reviewer or group reviewer has not yet cast a vote. 

❍ Accepted signifies that the user has cast an accept vote for the change package. 

❍ Rejected signifies that the user has cast a reject vote for the change package. 

Comments Displays information that reviewers optionally provide to clarify their votes. 

Changes Displays in tabular form the changes that were made to upon submission of the 


si viewcp also includes options that deal with formatting for the view. 

--format=value 

format for user-formatted text. 

--headerFormat=value 

header for user-formatted text. 


the height in pixels of the window. 

264 of 457

--noFormat=value 

format for user-formatted text. 

--noHeaderFormat=value 

header for user-formatted text. 

--noTrailerFormat=value 

trailer for user-formatted text. 

--trailerFormat=value 

trailer for user-formatted text. 

--width=value 

the width in pixels of the window. Can also be specified as fields=field1[:width1].... 

-x value 


-y value 


issue... 


issue identifies a specific issue that contains all change packages that you want to view; use 

spaces to specify more than one issue. 

issue:change package id identifies a specific change package to view; use spaces to specify 


DIAGNOSTICS 


PREFERENCES 



SEE ALSO 

Commands: 

si add, si ci, si closecp, si co, si cpissues, si createcp, si drop, si 

lock 



265 of 457

266 of 457

si viewcps 

displays all open change packages created by you 

SYNOPSIS 

si viewcps [--fields=field1[:width1],field2[:width2]...] [--filter=value] [--height=value] [--width=value] [-x 

value] [-y value] [--query=value] [--hostname=server] [--port=number] [--password=password] [-user=name] 

[(-?|--usage)] [(-F file|--selectionFile=file)] [(-N|--no)] [(-Y|--yes)] [--[no]batch] [-cwd=directory] 

[--forceConfirm=[yes|no]] [--[no]persist] [--quiet] [--myReviews] [(-g|--gui)] [-settingsUI=[gui|default]] 

[--status=[none|gui|default]] [--[no]persist] issue|issue:change package id... 

DESCRIPTION 

si viewcps displays all open change packages created by you. 

Options 

This command takes the universal options available to all si commands, as well as some general options. See the options reference page for 

descriptions. 


allows you to select fields to be printed, specified in the format field1[:width1],field2[:width2].... Specifying the column [:width] (in pixels) for each 

field is optional - widths are only available with the -g or -gui 

options. Under the CLI the fields are separated with a space. 


closeddate 

displays the date the change package was closed. 

creationdate 

displays the date the change package was created. 

description 

displays change package descriptions. 

id 

displays change packages IDs. 

summary 

displays change package summaries. 

issue 

displays the issue ID if the Integrity Manager integration is enabled. 

reason 

is only relevant when applying change packages, and is not used in the standalone Change Packages view. 

resolution 267 of 457

displays yes if the change package is a resolution change package, and no if it is not. 

resolutionlist 

displays the list of change packages resolved by a selected resolution change package (the resolution list is displayed by default if a 

resolution change package is selected). 

state 

displays current state of the change package. 

siserver 

displays the Source Integrity server the change package resides on. 

user 

displays the username who created the change package. 

--filter=value 

displays the change packages according to one of the following filters: 

state[:closed|:open|:submitted|:accepted|:rejected|:discarded|:commitfailed] 

displays change packages according to their state, which can be one of the following: 

:closed specifies that the change package is in a closed state (all changes committed to repository). 

:open specifies that the change package has in an open state (work in progress, available to add entries too). 

:submitted specifies that the change package has been submitted for review. 

:accepted specifies that the change package has been accepted by all reviewers. 

:rejected specifies that the change package has been rejected by at least one reviewer. 

:discarded specifies that the change package has been discarded. 

:commitfailed specifies that the change package has failed to commit to the repository. 

closeddate: 

displays closed change packages based on a specified closed date. Valid date formats are the following: between MM/dd/yyyy and 

MM/dd/yyyy, in the last|in the next number days|months|years yesterday|today|tomorrow. 

creationdate: 

displays change packages based on a specified creation date. Valid date formats are the following: between MM/dd/yyyy and 

MM/dd/yyyy, in the last|in the next number days|months|years yesterday|today|tomorrow. 

member: 

specifies a text string to filter change packages by member name. 

project: 

specifies a text string to filter change packages by project. 

variant: 

specifies a text string to filter change packages by variant. 268 of 457

description: 

specifies a text string to filter change packages by their description. 

summary: 

specifies a text string to filter change packages by their summary. 

type[:add|:addfromarchive|:drop|:import|:lock|:movememberto|:movememberfrom|:renamefrom|:renameto|:update|:updatearchive|:updaterevision] 

displays change packages based on their entry type. 

typemodifier[:committed|:pending] 

displays change packages based on their entry category. 

hasissue 

displays change packages that have an associated issue. 

pendingreviewby:name 

displays change packages that have not yet been accepted or rejected by a specified reviewer. 

acceptedby:name[;date] 

displays change packages accepted by a specified username on a specified date. Valid date formats are the following: between 

MM/dd/yyyy and MM/dd/yyyy, in the last|in the next number days|months|years yesterday|today|tomorrow. 

rejectedby:name[;date] 

displays change packages rejected by a specified username on a specified date. Valid date formats are the following: between 


rejectedby:name[;date] 

displays change packages rejected by a specified username on a specified date. Valid date formats are the following: between 


--myReviews 

displays change packages you are to review (which may include change packages not created by you). Change packages only appear in the list 

after they have been submitted for review. After you vote on the change package, it no longer appears in this list. 

--query=value 

the Integrity Manager query used to find change packages. For information on creating and using queries, see the Integrity Manager CLI 

Reference Guide. 

--[no]persist 



the height in pixels of the window. 

--width=value 

the width in pixels of the window. Can also be specified as fields=field1[:width1].... 

-x value 


-y value 


DIAGNOSTICS 


269 of 457

PREFERENCES 


SEE ALSO 

Commands: 

si add, si ci, si closecp, si co, si cpissues, si createcp, si drop, si lock 



270 of 457

si viewhistory 

displays a member's history 

SYNOPSIS 

si viewhistory [--fields=field1[:width1],field2[:width2]...] [--height=value] 

[--width=value] [-x value] [-y value] [--filter=filteroptions] 




[--[no]batch] [--cwd=directory] [--forceConfirm=[yes|no]] [(-g|--gui)] [--[no]persist] 

[--quiet] [--settingsUI=[gui|default]] [--status=[none|gui|default]] member... 

DESCRIPTION 

si viewhistory displays a member's history, one line per revision, per member. This is similar 

to si print and si rlog, but with different defaults. 

While sandboxes and projects allow you to manage and access project members and the contents 

of individual members, the history of changes are saved in member histories. 

MKS Source Integrity lets you save and recreate every stage (or revision) in the development of 

each member you use. When you make changes to a project member and check it back in, your 

changes are automatically added to the member history. 

Options 









author 

displays author names. 

cpid 

displays the associated change package identifier (applies only if change packages 

271 of 457

are enabled). 

date 

displays the working file date. 

description 

displays revision and project descriptions. 

labels 

displays labels. 

lockcpid 

displays the change package ID for the associated lock entry. 

lockdevpath 



single user to have a single lock on an archive per development path. Contact your 

administrator for more information. 

locked 

displays indicators for locked revisions. 

locker 

displays the user ID of the user with this revision locked, or null. 

lockhost 

displays the host name of the computer that locked the member. 

lockproject 




locksandbox 


relevant when viewing the information from the Locker Host. 

locktimestamp 

displays the time stamp for when the member was locked, otherwise null. 

revision 

displays the revision number. 

state 

displays the state. 


used with the -g or --gui options, specifies the height of the history view window, in pixels; 


--width=value 

used with the -g or --gui options, specifies the width of the history view window, in pixels; 


-x value 


-y value 


--[no]persist 


272 of 457



member... 


DIAGNOSTICS 


PREFERENCES 



SEE ALSO 

Commands: 


rlog, si sandboxinfo, si viewlabels, si viewproject, si 




273 of 457

si viewlabels 

displays a member's labels 

SYNOPSIS 

si viewlabels [--fields=field1[:width1],field2[:width2]...] 

[--height=value] [--width=value] [-x value] [-y value] [(-R|--[no|confirm]recurse)] 





[(-g|--gui)] [--[no]persist] [--quiet] [--settingsUI=[gui|default]] 


DESCRIPTION 

si viewlabels displays a member's labels: one label per line, showing the label and its revision 

number. 

Options 









cpid 

label 

displays the associated change package identifier (applies only if change packages 

are enabled). 


revision 



used with the -g or --gui options, specifies the height of the labels view window, in pixels; 


274 of 457

--width=value 

used with the -g or --gui options, specifies the width of the labels view window, in pixels; 


-x value 


-y value 


--[no]persist 




member... 


DIAGNOSTICS 


PREFERENCES 



SEE ALSO 

Commands: 


rlog, si sandboxinfo, si viewhistory, si viewproject, si 




275 of 457

si viewlocks 

displays locks 

SYNOPSIS 

si viewlocks [--format=value] [--headerFormat=value] [--noFormat] 

[--noHeaderFormat] [--noTrailerFormat] [(-r rev|--revision=rev)] [--range=value] 







[--[no]persist] [--settingsUI=[gui|default]] [--status=[none|gui|default]] member... 

DESCRIPTION 

si viewlocks displays the locks held in a project and some information about the members, for 

example: 

c:\app\connect.txt 1.4 mkern 

Jan 9, 2002 - 4:06 PM 

c:\app\source.txt 1.3 mkern 

Jan 9, 2002 - 4:06 PM 

c:\app\config.c 1.3 mkern 

Jan 8, 2002 - 2:26 PM 

Note: By default, si viewlocks displays the member names of locked members, not the 

working file names. 

Options 

This command takes some of the universal options available to all si commands, as well as some 

general options. See the options reference page for descriptions. 

See the si rlog reference page for descriptions of all options applicable to si viewlocks. 

DIAGNOSTICS 


276 of 457

PREFERENCES 



SEE ALSO 

Commands: 






277 of 457

si viewnonmembers 

displays non-members in a sandbox 

SYNOPSIS 

si viewnonmembers [--[no|confirm]includeFormers] 

[--exclude=file:pattern,dir:pattern...] [--include=file:pattern,dir:pattern...] 

[--fields=field1[:width1],field2[:width2]...] [-R|--[no|confirm]recurse] 

[-S|--sandbox=value] [--hostname=server] [--port=number] [--password=password] 

[--user=name] [(-?|--usage)] [(-Ffile|--selectionFile=file)] [(-N|--no)] [(-Y|--yes)] 


[--settingsUI=[gui|default]] [--status=[none|gui|default]] nonmember... 

DESCRIPTION 

si viewnonmembers displays non-members in a sandbox. 

From Source Integrity, you can view non-member files existent in your sandbox directory. The Non- 

Members view is useful when used recursively to identify all of the files that need to be placed 

under source control. By default, former members are not displayed in the Non-Members view. 

The Non-Members view does not display files that are: 

● deferred imported members 

● deferred add members from archive 

● pending members (add, add from archive, import) 

● working files from members that have been renamed but not resynchronized 

Non-members can only be viewed in a sandbox context, and not from any project view operation. 

Options 




specifies if to include members that have been dropped from the project, but where there 

still exists a working file in the sandbox directory.. 




278 of 457



allows you to select fields to be displayed, specified in the format 


optional - widths are only available with the -g or --gui options. 


absolutepath 

displays the absolute file path of the file. 

closestproject 

displays the project associated with the sandbox that is closest to the directory 

containing the file. 

closestsandbox 

displays the sandbox that is closest to the directory containing the file. 

lastmodified 

displays the date that the file was last modified. 

memberid 

displays the default member name for the file as it would appear if it was added to the 

nearest project. In the case where the nearest project is subproject, the relative path 

is displayed with the member name. 

size 

displays the size of the file in bytes. 

nonmember... 

identifies nonmembers to display; use spaces to specify more than one change package. 

DIAGNOSTICS 


PREFERENCES 



SEE ALSO 

Commands: 

si viewsandbox, si viewsproject, si add 

279 of 457



280 of 457

si viewprefs 

displays preferences 

SYNOPSIS 

si viewprefs [--[no]global] [--command=value] [--[no]showValidValues] 

[--[no]ask] [--ui=[unspecified|gui|cli|api]] [(-?|--usage)] [(-N|--no)] [(-Y|--yes)] 


[(-F file|--selectionFile=file)] [--settingsUI=[gui|default]] [--status=[none|gui|default]] 

DESCRIPTION 

si viewprefs displays preferences and configuration options. These settings are used to 

determine default behaviors for other commands. 

Your administrator can lock certain preferences from the Integrity Server, preventing you from 

configuring them using the si setprefs command. Preferences that are locked display 

(locked) at the end of the output line. The following preferences can be locked from the server 

by editing Source Integrity policies in the Administration Client: 

Tip: For information on editing the Source Integrity policies, see "Configuring the Integrity Server" 

in the Integrity Server Administration Guide. 






onLock si co 


si resync, 

si resynccp, si 

revert 





281 of 457

Warning: Do not edit the IntegrityClient.rc file manually, because preferences that appear 

more than once in the IntegrityClient.rc file can cause Source Integrity to behave 

unpredictably. 

Options 


options. See the options reference page for descriptions. For an easy way to see a list of 

commands and values that may be set, simply type the si viewprefs command, either piped 

through |more or redirected to a file, for example: 

si viewprefs --global --showValidValues >prefs.txt 

Alternatively, the --gui option presents a simple-to-use dialog box that lets you view and 

configure the preferences. 

--[no]global 

controls whether to view all preferences. 

--command=value 

identifies the command preference to be viewed. 

--[no]showValidValues 

controls whether to list valid values for the preferences. 

--[no]ask 

controls whether to view the ask control over the preference options. See the description for 

--[no]ask on the si setprefs command. 

--ui=[unspecified|gui|cli|api] 

controls whether to view the preference as it applies to the graphical user interface, the 

command line interface, application programming interface, or when the interface is 

unspecified. By default, --ui=cli is implied when issuing the si viewprefs. To view 

preferences for GUI behavior, however, you should specify --ui=gui. 

The preferences you see correlate to settings in the IntegrityClient.rc file, which can 

be seen as having the gui.si. or cli.si. prefix, or simply the si. prefix when it is unspecified. 

DIAGNOSTICS 


PREFERENCES 



282 of 457

SEE ALSO 

Commands: 

si loadrc, si setprefs 



283 of 457

si viewproject 

displays the contents of a project 

SYNOPSIS 

si viewproject [--fields=field1[:width1],field2[:width2]...] [--[no]filterSubs] 

[--height=value] [--width=value] [-x value] [-y value] [(-R|--[no|confirm]recurse)] 



[--password=password] [--user=name] [(-?|--usage)] [(-N|--no)] [(-Y|--yes)] 

[--[no]batch] [--cwd =directory] [--forceConfirm=[yes|no]] [(-g|--gui)] 

[--[no]persist] [--quiet] [--settingsUI=[gui|default]] [(-F file|--selectionFile=file)] 

[--status=[none|gui|default]] member/subproject... 

DESCRIPTION 

si viewproject displays the contents of a project and some information about the members, for 

example: 

connect.txt 1.4 archived 

source.txt 1.3 archived 

config.c 1.3 archived 

Note: Specifying si viewproject -S sandbox does not view the sandbox; it redirects through 

the sandbox to view the project. Use si viewsandbox to view a sandbox. 

Options 






optional. Widths are only available with the -g or --gui options. Under the CLI the fields 



archiveshared 

displays indicators for members that share another member’s archive. This column is 

284 of 457

valid only if you are using the database repository. 

attributes 

displays member attributes. 

context 

displays the name of the project, with the parent project name if applicable, type of 

project, and if build or variant. 

cpid 

displays the change package associated with the operation that set the member 

revision. 

creationcpid 

displays the change package that created the revision that is currently the member 

revision. This revision may be different from the Member CPID if an import, add 

member from archive, or set member revision operation was used. 

frozen 

displays indicators for frozen members. 

indent 

indents subprojects. 

labels 


locked 

displays indicators for locked revisions. 

locker 

displays user identifiers for those who have locked revisions. 

lockercpid 

displays the change package associated with the lock on the member revision. 

lockdevpath 



single user to have a single lock on an archive per development path. Contact your 

administrator for more information. 

lockhost 


lockproject 




locksandbox 


relevant when viewing the information from the Locker Host. 

locktimestamp 

displays the time stamp for when the member was locked. 

memberarchive 

displays the name and path of the member archive. 

memberdescription 

displays the member description. 

285 of 457

memberrev 

displays the member revision. 

membertimestamp 

displays the member timestamp. 

name 


newrevdelta 

displays indicators for new revisions. 

pendingcpid 

displays the change package associated with a pending operation. 

state 

displays the member state. 

type 

displays the type of each item in the project: project, subproject, shared-subproject, 

shared-variant-subproject, shared-build-subproject, or member. 

--[no]filterSubs 

controls whether to display subprojects and directories that do not contain members 

matching the current filter. 


used with the -g or --gui options, specifies the height of the project view window, in pixels; 


--width=value 

used with the -g or --gui options, specifies the width of the project view window, in pixels; 


-x value 


-y value 


--[no]persist 




member/subproject... 

identifies a specific member or subproject; use spaces to specify more than one. 

DIAGNOSTICS 


PREFERENCES 



286 of 457

SEE ALSO 

Commands: 



viewprojecthistory , si viewsandbox 



287 of 457

si viewprojecthistory 

displays a history of the project 

SYNOPSIS 

si viewprojecthistory [--fields=field1[:width1],field2[:width2]...] [--height=value] 





[--[no]batch] [--cwd =directory] [--forceConfirm=[yes|no]] [(-g|--gui)] 

[--[no]persist] [--quiet] [--settingsUI=[gui|default]] [--status=[none|gui|default]] 

[--xmlapi] 

DESCRIPTION 

si viewprojecthistory displays a history of the project, including information on each 

historical checkpoint. 

Options 









author 

displays author names. 

date 

displays the project checkpoint date. 

description 

displays revision and project descriptions. 

labels 


revision 


288 of 457

state 

displays the revision state. 


used with the -g or --gui options, specifies the height of the project history view window, 

in pixels; value must be a whole number. 

--width=value 

used with the -g or --gui options, specifies the width of the project history view window, in 


-x value 


-y value 


--[no]persist 




DIAGNOSTICS 


PREFERENCES 



SEE ALSO 

Commands: 


rlog, si sandboxinfo, si viewhistory, si viewlabels, si viewproject, si 

viewsandbox 



289 of 457

si viewrevision 

opens a revision for viewing 

SYNOPSIS 

si viewrevision [--[no|un]expand] [(-rrev|--revision=rev)] 






DESCRIPTION 

si viewrevision opens a member revision for viewing. 

Options 







keywords are: 

$Author$ 

$CompanyInfo$ 

$Date$ 

$Header$ 

$Id$ 

$Locker$ 

$Log$ 

$Name$ 

$ProjectName$ 



$RCSfile$ 

$Revision$ 



290 of 457

$Source$ 

$State$ 

member... 


DIAGNOSTICS 


PREFERENCES 



SEE ALSO 

Commands: 

si ci, si co, si edit, si lock, si unlock 



291 of 457

si viewsandbox 

displays the contents of a sandbox 

SYNOPSIS 

si viewsandbox [--[no]includeDropped] [--fields=field1[:width1],field2[:width2]...] [--[no]filterSubs] 

[--height=value] [--width=value] [-x value] [-y value] [(-R |--[no|confirm]recurse)] [-filter=filteroptions] 


[--password=password] [--user=name] [(-?|--usage)] [(-F file|--selectionFile=file)] [(-N |--no)] [(-Y|-yes)] 

[--[no]batch] [--cwd=directory] [--forceConfirm=[yes|no]] [(-g|--gui)] [--[no]persist] [--quiet] 

[--settingsUI=[gui|default]] [--status=[none|gui|default]] current or dropped member/subproject... 

DESCRIPTION 

si viewsandbox displays the contents of a sandbox, for example: 

Options 

c:\Documentation\xml_man\si_about.1.xml archived 1.6 

c:\Documentation\Man_Pages\xml_man\si_acv.1.xml archived 1.7 

c:\Documentation\Man_Pages\xml_man\si_add.1.xml archived 1.7 sueq Jun 21, 2002 - 10:14 

AM 

Working file 2,739 bytes smaller, older (Jun 20, 2002 - 1:46:27 PM) 

c:\Documentation\Man_Pages\xml_man\si_addlabel.1.xml archived 1.6 sueq Jun 21, 2002 - 

10:14 AM 


c:\Documentation\Man_Pages\xml_man\si_addmemberattr.1.xml archived 1.4 sueq Jun 21, 

2002 - 10:14 AM 


c:\Documentation\Man_Pages\xml_man\si_addprojectattr.1.xml archived 1.4 

c:\Documentation\Man_Pages\xml_man\si_addprojectlabel.1.xml archived 1.4 

c:\Documentation\Man_Pages\xml_man\si_appendrevdesc.1.xml archived 1.6 

c:\Documentation\Man_Pages\xml_man\si_archiveinfo.1.xml archived 1.5 

This command takes the universal options available to all si commands, as well as some general options. See the options 

reference page for descriptions. 

--[no]includeDropped 

controls whether to include members dropped from the project that still have working files in your sandbox. Dropped 

members will be marked as dropped. 


allows you to select fields to be printed, specified in the format field1[:width1],field2[:width2].... Specifying the column 

[: width] (in pixels) for each field is optional - widths are only available with the options. Under the CLI the fields are 

separated with a space>. 


archiveshared 

displays indicators for members that share another member’s archive. This column is valid only if you are using 

the database repository. 

attributes 

displays member and project attributes. 

context 

displays the name of the project, with the parent project name if applicable, type of project, and if build or variant. 

292 of 457

cpid 

displays the change package associated with the operation that set the member revision. 

creationcpid 

displays the change package that created the revision that is currently the member revision. This revision may 

be different from the Member CPID if an import, add member from archive, or set member revision operation 

was used. 

deferred 

displays all deferred operations. 

frozen 

displays indicators for frozen members. 

indent 

indent subprojects. 

labels 


locked 

displays an indicator if the member revision is locked. 

locker 

displays user identifiers for those who have locked revisions. 

lockercpid 

displays the change package associated with the lock on the member revision. 

lockdevpath 

displays the name of the development path where the lock on the revision was made from. This information is 

relevant when the locking policy is set to devpath, allowing a single user to have a single lock on an archive per 

development path. Contact your administrator for more information. 

lockhost 


lockproject 

displays the name and path of the project where the member revision was locked from. If the member revision 

was locked from a shared subproject, it is the subproject name and path that are displayed. 

locksandbox 

displays the name of the sandbox where the lock on the revision was made, and is relevant when viewing the 

information from the Locker Host. 

locktimestamp 

displays the time stamp for when the member was locked. 

memberarchive 

display the name of the archive to which the member refers. 

memberdescription 

displays the revision description assigned to the sandbox member. 

memberrev 

displays the member revision. 

membertimestamp 

displays the date and time the member revision is set. 

merge 

displays any merge information between member revisions. 

name 


newrevdelta 

displays indicators for new revisions. 

pendingcpid 

displays the change package associated with a pending operation. 

revsyncdelta 

displays an indicator for out of sync members. 

state 

displays the member state. 

type 

displays the type of each item in the sandbox: sandbox, subsandbox, shared-subsandbox, shared-variantsubsandbox, 

shared-build-subsandbox, or member. 

wfdelta 

293 of 457

displays an indicator when the working file is different from the member revision. 

workingarchive 

displays the name of the archive from which the working file is derived. 

In the case where the working file was derived from an archive that was based on a server-side system setup 

(based on some default RCSPath or WorkToArch setting, as opposed to an explicit archive=reference), the 

Working Archive field displays the value default:server directory. The actual name of the archive the working 

file was derived from can then be determined from the value for the Archive Name field. 

workingcpid 

displays the change package associated with a deferred or a lock operation performed by the current user from 

the current sandbox. 

workingrev 

displays the working file revision. 

--[no]filterSubs 

controls whether to display subsandboxes and directories that do not contain members matching the current filter. 


used with the -g or --gui options, specifies the height of the sandbox view window, in pixels; value must be a whole 

number. 

--width=value 

used with the -g or --gui options, specifies the width of the sandbox view window, in pixels; value must be a whole 

number. 

-x value 


-y value 


--[no]persist 

controls whether this presentation of information should continue to be updated as new information becomes available. 

--nopersist forces a static "snapshot" of information, while --persist gives real-time updates. 


identifies a specific member or subproject that currently exists in the project, or one that has been dropped from the 

project. Use spaces to specify more than one. 

DIAGNOSTICS 


PREFERENCES 


SEE ALSO 

Commands: 

si archiveinfo, si memberinfo, si mods, si print, si revisioninfo, si rlog, si sandboxinfo, si 

viewhistory, si viewlabels, si viewproject, si viewprojecthistory 



294 of 457

ACL (Access Control List) 

permissions for MKS Integrity Suite ACL interaction 

DESCRIPTION 

The ACL (Access Control List) permissions control user access to MKS Integrity Suite functions (in 

both MKS Source Integrity and MKS Integrity Manager) by associating development objects and 

operations with specific permissions. For example, whenever a user initiates an operation such as 

checking a file in or out, Source Integrity queries the ACL database to determine whether the user 

has permission to perform the operation. This reference page is provided as a guide to the ACL 

permissions. 

There are five server-level ACLs shipped by default: mks:aa--controls the Login access to the AA 

application for managing the ACLs, mks:aa:mks--controls Read and Update access to the ACLs, 

mks:im controls access to Integrity Manager operations, mks:patch controls the Download 

permission required for service pack management, and mks:si--controls access to Source Integrity 

operations. For the most part, however, you will be working with project ACLs, that control the 

permissions for a particular directory. Working with member ACLs is also possible, which control 

permissions for specific files -- this would be for those rare circumstances where security on 

specific, individual files must be heavily controlled and where the administrative costs are known 

and accepted. 

The ACL name itself follows a specific hierarchical format: 

● The default server-level ACL is named mks:si. All project and member ACLs will inherit 

permissions from this one. 

● Project-level ACL names include a specific prefix, taking the format 

mks:si:project:id:. The project directory is relative to the root of the 

Integrity Server. 

● Subproject ACLs have the same format as projects, simply appending the subdirectories 

using colons (:) instead of slashes. 

● Variant project ACLs have a slightly different prefix, taking the format 

mks:si:project:devpath::id. 

● Member ACLs simply specify the file name in the ACL name, such as 

mks:si:project:id::. 

● Archive ACLs simply specify the archive name in the ACL name, such as 

295 of 457

mks:si:archive:. 

ACL PERMISSIONS 

You must have the appropriate ACL permissions before you can perform Source Integrity and 

Integrity Manager operations. For details on configuring ACLs, see the Integrity Server 

Administration Guide. 

Server Permissions 

Possible Source Integrity server-related permissions: 

AdminProxy 

For MKS Customer Care only. Allows a user to perform administrative functions on the 

proxy 

Prerequisites: none. 

AdminServer 


server. 


DebugProxy 

For MKS Customer Care only. Allows a user to perform diagnostic functions on the proxy. 


DebugServer 

For MKS Customer Care only. Allows a user to perform diagnostic functions on the server. 


EditPolicy 

Allows a user to modify and create Source Integrity policies on the Integrity Server. The Edit 

Policy permission should be restricted to administrators and Source Integrity project 

managers 

Prerequisites: Login. 

Login 

296 of 457

Allows a user to log in to Source Integrity. 


ViewPolicy 

Allows a user to view Source Integrity policies on the Integrity Server. The View Policy 

permission should be restricted to administrators and Source Integrity project managers. 


Member Permissions 

Possible Source Integrity member-related permissions are: 

ApplyLabel 

Allows a user to add labels to revisions or move labels between revisions. 

Prerequisites: Login, OpenProject. 

BreakLock 

Allows a user to break locks held by other users. 

Prerequisites: Login, OpenProject, Lock, Unlock. 

CheckIn 

Allows a user to check in working files as new revisions of members. 

Prerequisites: Login, OpenProject, ApplyLabel, Lock, ModifyAuthor, 

ModifyMemberRev, ModifyMemberAttribute. 

DeleteLabel 

Allows users to delete a label from a revision. 


DeleteRevision 

Allows a user to delete revisions from the member history. 

Note: 

This permission allows users to irrevocably delete revisions from the member history. 

Administrators should assign this permission carefully. 


297 of 457

Demote 

This permission allows a user to change the promotion state of revisions from a higher 

setting to a lower one, when the States= configuration option defines a sequence of 

promotion states. For details, see the Integrity Server Administration Guide. 


FetchRevision 

Allows a user check out member revisions. 

Prerequisites: Login, OpenProject, Lock, ModifyMemberRev. 

Freeze 

Allows a user to freeze members. When a member is frozen, all Source Integrity operations 

are run on the frozen member revision. 

Lock 


Allows a user to lock revisions. 


ModifyAuthor 

Allows a user to change the author name associated with a revision. 


ModifyMemberAttribute 

Allows a user to set an attribute for a member that can be used later in a search. 


ModifyMemberRule 

Allows a user to configure a member revision rule that can be applied to one or more 

members. 


MoveLabel 

Allows a user to move a member label to another revision within the member history. 

298 of 457

Prerequisites: Login, OpenProject, ApplyLabel. 

Promote 

This permission specifies that a user may promote revisions from the current promotion 

state to a higher state, when the States= configuration option defines a sequence of 

promotion states. For details, see the Integrity Server Administration Guide. 


ShareArchive 

Allows sharing of member archives between two or more members. 

Thaw 

Note: 

Archive sharing is not recommended. Instead, creating variant sandboxes is 

considered a better practice. 

Prerequisites: Login, OpenProject, Checkpoint, CheckIn, Lock. 

Allows a user to thaw frozen members. 


Change Package Permissions 

Possible Source Integrity change Package related permissions are: 

ChangePackageAdmin 

Allows a user to edit, discard, close, and submit change packages; as well as move or 

discard change package unties, regardless of any documented user restrictions. 


CreateChangePackage 

If you are using Source Integrity only, this permission allows a user to create change 

packages. 

If the Source Integrity and Integrity Manager Integration is enabled, this permission allows a 

user to create change packages based on the Change Package Creation Policy for the type 

that they want to create change packages for. 


299 of 457

SelfReview 

Allows user to accept change packages under review that were created by that user. 

SuperReview 

Allows a user to accept or reject a change package under review regardless of the reviewer 

rules. Note: This permission supersedes the SelfReview permission. 

Project Permissions 

Possible Source Integrity project-related permissions are: 

AddMember 

Allows a user to add new members to projects through a sandbox. 

Prerequisites: Login, OpenProject, Lock, ShareArchive, ModifyAuthor. 

AddSubproject 

Allows a user to re-add dropped subprojects to a project. 


ApplyProjectLabel 

Allows a user to add labels to projects or move labels between revisions of the project. 


CheckPoint 

Allows a user to check in a new revision of a project (that is, checkpoint the project). 

Prerequisites: Login, OpenProject, ApplyLabel, Promote, PromoteProject, 

ApplyProjectLabel. 

ConfigureSubproject 

Allows a user to configure a subproject's type. A subproject can be configured as a Normal, 

Variant, or Build subproject. 


CreateDevPath 

Allows a user to create new development paths for variants of a project. 


300 of 457

CreateProject 

Allows a user to create new projects. 


CreateSubproject 

Allows a user to create new subprojects below existing projects. 


DeleteProjectLabel 

Allows a user to delete a label from a project revision. 


DemoteProject 

This permission specifies that a user may demote projects from a higher promotion state to 

a lower state, when the States= configuration option defines a sequence of promotion 

states. For details, see the Integrity Server Administration Guide. 


DropDevPath 

Allows a user to drop a development path, also known as "dropping variants" from a project. 


DropMember 

Allows a user to remove members from projects. The member archive remains, but the 

member is no longer treated as part of the project. 


DropProject 

Allows a user to drop one or more top-level, registered projects from the server. The 

projects then become unregistered projects. 


DropSubProject 

Allows a user to drop one or more subprojects from the server. The projects then become 

301 of 457

unregistered projects. 


ImportProject 

Allows a user to import one or more projects from an earlier version of Source Integrity. The 

import operation registers the project on the Integrity Server. 


ModifyMemberRev 

Allows a user to make changes to existing member histories. 


ModifyProjectAttribute 

Allows a user to set an attribute for a project, which can be used later in a filter or search. 


MoveProjectLabel 

Allows a user to move a project label to another project revision within the project history. 

Prerequisites: Login, OpenProject, ApplyProjectLabel. 

OpenProject 

Allows a user to open existing registered projects. This is required for most actions. 

Note: 

When OpenProject is granted or denied on a project, clients accessing the project 

must disconnect and then reconnect in order to get the new permission set. If you do 

not disconnect and reconnect your client, you may see unexpected behavior due to 

out-of-date permissions. 


PromoteProject 

This permission specifies that a user may promote projects from the current promotion state 

to a higher state, when the States= configuration option defines a sequence of promotion 

states. For details, see the Integrity Server Administration Guide. 


302 of 457

RestoreProject 

Allows a user to restore a project to a particular checkpointed version. 

Prerequisites: Login, OpenProject, Checkpoint. 

SnapshotSandbox 

Snapshot creates and records the state of the user’s sandbox as a branched project revision 

within the project history. 

Prerequisites: Login, OpenProject, Checkpoint, AddMember, DropMembers. 

MKS Integrity Manager Permissions 

Possible permissions related to Integrity Manager are: 

Admin 

Allows administrative privileges for working with Integrity Manager. 


AdminProxy 


proxy 


AdminServer 


server. 


CreateCPType 

Allows the assigned user or group to create a custom change package type. For information 

on custom change package types, contact MKS Customer Care. 


CreateProject 

Allows the assigned user or group to create a new top level Integrity Manager project and 

assign another Integrity Manager Project Administrator. This permission can be used to 

extend the capability of the Integrity Manager Project Administrator. Denying this permission 

303 of 457

means the user cannot create a new top level project or assign another Project 

Administrator. 


CreateQuery 

Allows a user to create a new query in Integrity Manager. Denying this permission restricts 

the user to using only those queries that already exist on the system. 


CreateType 

Allows the assigned user or group to create a new type in Integrity Manager or assign 

another Integrity Manager Type Administrator. This permission can be used to extend the 

capability of the Integrity Manager Type Administrator. Denying this permission means the 

user cannot create any new types or assign another Type Administrator. 


Login 

Allows a user to login to Integrity Manager. 


ModifyMyNotification 

Allows a user to modify personal e-mail notification preferences in Integrity Manager. 

Prerequisites: Login, ViewMyNotification. 

ViewAdmin 

Allows a user to view administrative information related to Integrity Manager. 


ViewMyNotification 

Allows a user to view personal e-mail notification preferences in Integrity Manager. 

SEE ALSO 


304 of 457

Commands: 

aa acls, aa addaclentry, aa availablepermissions, aa deleteacl, aa 

deleteaclentry, aa groups, aa users, aa viewacl 


diagnostics 

305 of 457

NAME 

cc — cc configuration files. 

INTRODUCTION 

cc -- Miscellaneous Information 

cc reads commands from the configuration file, and executes them to run the appropriate compiler 

and linker. The command line that was passed to cc is examined by the code in the configuration 

file. If you are familiar with MKS Toolkit, you may notice that the commands resemble AWK or MKS 

KornShell commands. However, these commands are sufficiently different that you should study 

them carefully before using them. Look at sample configuration files, and experiment with cc in its 

interactive mode as you program new configuration files. The program tries to load the script 

$ROOTDIR/etc/compiler.ccg. You can modify this behavior by setting the CCG environment 

variable. If CCG contains the name of a file, cc loads and runs that file; if CCG contains the name 

of a directory, the program loads and runs the script in that directory. 

If you rename the cc executable, it attempts to find its default configuration in a .ccg file with the 

same base name as the renamed executable. For example, if you rename cc.exe to c89.exe, 

then c89 looks for a default configuration file named c89.ccg in ROOTDIR/etc. 

In any case, if you have set the CCG environment variable, its value takes precedence. If CCG 

contains a file name, cc looks for the default configuration in that file. If CCG contains a directory, 

cc looks for the default configuration in a .ccg file in that directory. The base name of the .ccg 

file is the same as that of the executable. That is, if the executable is cc.exe, the default 

configuration is looked for in $CCG/cc.ccg and if the executable has been renamed c89.exe, 

the default configuration is looked for in $CCG/c89.ccg. 

To enter interactive mode, set the environment variable CCG to the value - or stdin. cc then 

reads its configuration file from its standard input. This is useful for debugging new configuration 

files: you can interactively enter commands, dump cc's symbol table, and follow the execution of 

your cc program. 

COMMENTS 

A comment starts with a # character and extends to the end of the line. This is the same 

convention as MKS Make, AWK, and the MKS KornShell. 

LITERALS 

306 of 457

cc can manipulate three types of objects: integers, strings, and arrays of strings or integers. Since 

arrays are limited to one dimension, they are also called vectors. Unlike AWK, cc does not support 

floating point numbers. 

Integers are written in the usual way. Here are some sample integers: 

123 -49 20000 

Strings are written with quotes around them, and cannot extend across a line. Empty strings are 

written as "". The following escape sequences are allowed within strings: 

\a alert (bell) 

\b backspace 

\h hard space 

\i hard tab 

\n newline 

\r carriage return 

\t horizontal tab 

\v vertical tab 

\\ escaped \ 

\" embedded " 

\ooo ASCII character with octal value ooo 

Here are some sample strings: 

"hello" "\"embedded\" quotes" 

"\\escaped backslash, with tab\t and newline\n" 

A vector is list of integers or strings, separated by commas and surrounded by braces, as in 

{ 1, 2, 3 } 

{ "strings", 1, "and numbers" } 

{ a++, ++c } 

{ } 

Because these are dynamic, the contents of the vector need not be constant expressions. For 

example, a++ is valid in a vector list. Empty vectors are written as {}. You indicate a vector's 

elements with the bracket [] operator. 

Indexable Objects 

Both strings and vectors can be indexed -- indexing is 0-origin. Indexable objects have an 

associated cursor that indicates the current position of the index. This means you can treat any 

307 of 457

indexable object as a stream. (The cursor is actually associated with the value of a variable rather 

than with the variable itself; if you assign a new value to a variable, the cursor is reset to the 

origin.) The rewind statement lets you rewind the stream to the start of an object. Several 

functions are provided for dealing with indexable objects -- read(), offset(), and tail(). 

# Setup the string: 

stream="Alph" ; 

# Read and print the first 3 elements; 

# this prints "A l p" 

println read(stream), read(stream), read(stream); 

# Rewind the stream: 

rewind(stream); 

# Print the first two elements 

# and the index of the next ("A l 2"): 

println read(stream), read(stream), offset(a); 

# Print the remainder of the string ("ph"): 

println tail(stream); 

To look ahead on a stream, use indexing combined with the offset. See String/Vector Operations 

for more information on the functions. 

VARIABLES 

A variable is a name with an associated value. The name follows the usual rules for C identifiers; 

the first character must be a letter or underscore (_), followed by zero or more letters, digits, or 

underscores. 

Variables are created as they are first seen in cc input. Any variable can have any type of value; 

the type changes automatically if a value of a different type is assigned. 

BUILT-IN VARIABLES 

Several variables have pre-assigned values at the start of a cc program. You can change these 

values. The variables are: 

ARGV 

DIRSEPSTR 

This variable is assigned a vector containing the strings that appeared on the command line 

that called cc. Note that the name of the program is not provided. ARGV is typically 

examined, and used to build new argument lists for the compiler or linker that is being used. 

308 of 457

ECHO 

Contains the characters that can be used to separate path names into the component 

directories. On Windows systems, it is initially set to the string /\:. although the default 

startup.mk file modifies this based on the value of the SHELL environment variable. See 

the description of filepath(). 

Originally assigned the empty (null) string, corresponding to a false expression. If it is later 

assigned a true value, the exec and ovl_exec operations (described later) print the 

commands as they are about to be executed. 

NORUN 

Originally assigned the empty (null) string, corresponding to a false expression. If it is later 

assigned a true value, the exec and ovl_exec operations (described later) only echo their 

arguments, and exec returns as though the command succeeded, while ovl_exec 

terminates cc with a return value of 0. Setting NORUN in this way corresponds to running 

Make with the -n option. By assigning non-null values to both ECHO and NORUN, you can get 

cc to display the commands that it attempts to execute to compile a program. 

true 

Assigned the integer value 1, true is used internally by cc to denote a true expression. You 

should not change this value; if you change the value of true to be an expression that is 

considered false (see EXPRESSIONS), cc may not function correctly. 

PROGRAMS 

A cc program consists of a number of statements, each of which is read and then executed. 

During the reading of a statement, a syntax error causes cc to print a diagnostic message, and 

then cc goes on to the next statement. During the execution of a statement, an error causes cc to 

print a diagnostic message. If cc finds a syntax error as it is reading a statement, it prints a 

diagnostic message and goes on to the next statement. While executing a statement, if cc finds an 

error, it prints a diagnostic message; if an expression is being calculated, then the null string is 

returned as the value of the expression. 

STATEMENTS 

This section describes the statements that may be used in input to cc. In the following, the 

characters {} are used to indicate zero or more occurrences of the enclosed items. The characters 

[] indicate an optional occurrence of the enclosed items. 

The following table summarizes statements allowed in cc: 

Description Syntax 

309 of 457

Advance advance name ; 

Assignment name = expr ; 

name[expr1] = expr2 ; 

Assign & concatenate name |= expr ; 

name[expr1] |= expr2 ; 

Break loop break [expr] ; 

Close file close filename ; 

Delete file delete filename ; 

Dump debugging info dump ; 

Empty statement ; 

Execute command exec expr ; 

Exit exit ; 

For for (name in expr) 

do statements done 

For for (expr1; expr2; expr3) 

do statements done 

Functions function name([arg1{[,arg2]]}) 

{ statements } 

If if (expr1) statements 

{ elif (expr2) statements } 

[ else statements ] 

fi 

Open file open filename ; 

Overlay file ovl_exec cmd_expr1 {,expr2} ; 

Print expression(s) print expr1 {,expr2} ; 

Print line println expr1 {,expr2} ; 

Print to file print expr1 {,expr2} -> filename; 

println expr1 {,expr2} -> filename; 

Rewind cursor rewind indexable_object 

While while (expr) do statements done 

Table 1: Summary of cc Statements 

In this definition, statements means a list of statements, and expr, expr1, and expr2 mean any 

legal expression as described a bit later. The expression value is used as a logical expression. See 

EXPRESSIONS for the description of what values are considered true and false. 

Empty statement 

An empty statement is written as a single semicolon (;). It has no effect. 

310 of 457

If statement 

An if statement has the form: 

if ( expression ) statements 

{ elif ( expression ) statements } 

[ else statements ] 

fi 

Note that fi is required to end the if statement. Any number of elif's can be inserted before the 

end of the if statement. 

While statement 

A while statement has the form: 

while ( expression ) do statements done 

The done is required to mark the end of the statements. The meaning is similar to the C while 

loop. 

For loop 

A for statement has one of these forms: 

for ( name in expression ) do statements done 

for ( expr1; expr2; expr3 ) do statements done 

In the first form, the name must be a variable name, and the expression must evaluate to a vector 

or string. If the vector is not empty, the statements are executed repeatedly; on each iteration, 

name is assigned each successive value in the vector. The second form is much more like the C 

language for loop. Usually, the first expression initializes some variable, the second expression 

tests it, and the third expression increments or decrements it. 

Advance 

An advance statement has the form: 

advance name ; 

where name is a variable name used in an enclosing for loop. This statement immediately 

assigns to name the value it would normally have been given in the next iteration of the for loop, 

and subsequent iterations skip this value. 

Break loop 

311 of 457

A break statement has the form: 

break [expr] ; 

where expr is the number of levels to break out of. If no expression is specified, break exits the 

current loop (expr is 1). 

Exit Program 

The exit statement has the form: 

exit expression ; 

This terminates cc with the integer-valued expression as its exit value. 

Dump Debugging Information 

The dump statement is a debugging aid. 

dump ; 

outputs the names and values of all variables currently defined to the standard output. 

Print Expression 

There are several printing statement forms. 

print expression { , expression } ; 

prints the values of the given expressions on the standard output. If more then one expression is 

given, they are printed with a single blank separating each item. print does not put a newline 

character at the end of the output. 

println expression { , expression } ; 

is similar to the previous format, but does print a newline at the end of the list of expressions. 

print expression { , expression } -> filename ; 

println expression { , expression } -> filename ; 

are similar to the other printing statements, but they print to the given file instead of to the standard 

output. The filename is given as a string-valued expression. If the file does not exist, it is created; if 

it already exists, output is appended to the end of the current contents. 

Close File 

312 of 457

To close a given file, use 

close filename ; 

The filename is given as a string-valued expression. If you use a printing statement to write to a 

file, it is important to close the file before cc runs a program that requires the contents of the file to 

be up-to-date. 

Delete File 

To delete a given file, use 

delete filename ; 

You can use this to get rid of temporary (work) files created by earlier statements in the cc 

program. The file name is given as a string-valued expression. 

Define Function 

You can define a function using the function statement, which has the form: 

function name ( [arg1{, arg2}] ) 

{ 

statements 

} 

Execute a command 

To execute a command, use 

exec expression { , expression } ; 

Each expression is converted into a string (if necessary) and then concatenated into a command 

string (with a single blank between each expression in the list). For example, 

exec "cp","infile","outfile" ; 

executes the command 

cp infile outfile 

The exec statement executes the command and then goes on to the next statement. (See the 

exec expression following for ways to get the return status of the executed command.) The 

behavior of exec can be changed by the values of the ECHO and NORUN variables. 

313 of 457

Overlay Execute 

The statement 

ovl_exec expression { , expression } ; 

is similar to an exec statement. In this case, the memory used by cc is overlaid with the command 

to be run, and cc is effectively terminated. This frees the memory space that cc is occupying for 

the executed program. The behavior of ovl_exec can be changed by the values of the ECHO and 

NORUN variables. 

Rewind Stream 

The rewind statement has the form: 

rewind indexable_object ; 

where indexable_object is a string or vector. This statement moves the cursor associated with 

indexable_object back to the origin. For more about indexable objects, see Indexable Objects. 

EXPRESSIONS 

Expressions are created by combining literal strings, integers, vectors, and variables, with the 

operators listed a bit later. 

An expression has a type: integer, string, or vector. When an integer value is required and a string 

or vector is provided, some operators convert the vector into a string, and then interpret that string 

as an ASCII sequence representing a number. For example, "123" has the integer value 123 

when used in arithmetic operations. By the same token, if a string is required, an integer value is 

converted into a string in the same way. 

Some expressions are calculated by determining if operands are true or false. The following are 

considered false: 

● the integer 0 

● the null string "" 

● an empty vector { } 

Other objects are considered true. The built-in variable true can also be used as a condition. 

Operators are grouped in precedence classes that are similar to those of the C programming 

language. Each section that follows describes a group of operators in a single-precedence class. 

The order of the sections gives the order of precedence. 

314 of 457

Order of Operations 

A++ A-- ++A --A pre- and post-increment and decrement 

-A (A) V[a] unary minus, grouping, array element 

A*B A/B integer multiplication and division 

A+B A-B addition and subtraction 

A%B modulus 

: 

A==B A!=B equality comparison 

AB A=B relational comparison 

A&&B A||B !A logical AND, logical OR, logical negation 

, 

-> file redirection 

length(A) length operation 

A | B string/vector concatenation 

A=B A|=B assignment 

A and B are any expression. 

V is any vector expression. 

Primary Expressions 

These expressions have the highest precedence. 

- expression 

gives the negative of an integer expression. 

( expression ) 

Table 2: cc Order of Operations 

gives the value of the expression inside the parentheses, and you use it to change the order of 

315 of 457

evaluation of expressions. 

indexable_object[expression] 

obtains the value of a specific indexable element. Indexable objects (vectors and strings) are 

indexed with 0-origin. If a vector subscript is out of range, an error message is displayed, and the 

null string is returned. As a special case, the 0-th element of a 0-length vector does not cause an 

error; instead, its value is the null string. 

Arithmetic Operators 

The standard multiplication operators are: 

expression1 * expression2 

expression1 / expression2 

expression1 % expression2 

representing integer multiplication, division, and the modulus. Non-integer operands are converted 

to integers in the usual way. 

The standard addition operators are: 

expression1 + expression2 

expression1 - expression2 

representing addition and subtraction. Non-integer operands are converted to integers in the usual 

way. 

Equality Operators 

The result of: 

expression1 == expression2 

is true if the two expressions have equal values. 

expression1 != expression2 

is true if the two expressions are not equal. 

In both cases, if either operand is an integer, the other is converted into an integer for the purposes 

of comparison; otherwise, both expressions are converted into strings, and then compared. 

316 of 457

Relational Operators 

The relational operators are: 

expression1 > expression2 

expression1 < expression2 

expression1 >= expression2 

expression1

If expression is a vector, the value is the number of elements in the vector. If expression is a string, 

the value is the number of characters in the string; otherwise, the value is 0. 

String/Vector Operators 

The operator | concatenates strings or vectors. The form is 

expression1 | expression2 

where expression1 must be a string or vector. If expression1 is a string, the second argument is 

converted to a string and the two strings are concatenated for the result. For example, in 

X = "hello"; 

X = X | " good" | "bye"; 

the variable X is assigned the value 

"hello goodbye" 

You can use the shorthand notation |= to append to the end of an existing string, as in 

x = "hello"; 

x |= " good" | "bye"; 

which has the same result. 

If the first argument of the | operator is a vector, the second argument is added as a new 

component to the vector. In this way, you can assign values to a vector incrementally. You can use 

the |= operator as a shorthand assignment. For example: 

x = {} # ensure x is a vector 

x |= 1; # x is now { 1 } 

x |= "so"; # x is now { 1, "so" } 

x |= 2 | 3; # x is now { 1, "so", "23" } 

# Remember, the '|' is applied to '2' and '3', 

# forming a string, that is then added 

x |= { 4, 5 }; # x is now { 1, "so", "23", 4, 5 } 

Assignments 

There are several assignment expressions. 

name = expression ; 

318 of 457

assigns the value of the expression to the given named variable. 

name[expression1] = expression2 ; 

assigns the value of expression2 to the element of the vector variable specified by expression1. It 

is an error to use an index greater then the length of the vector. 

name |= expression ; 

name[expression1] |= expression2 ; 

are concatenation assignments. The value of the right hand side is concatenated to the existing 

value of the left hand side. See String/Vector Operators for more about concatenation. 

Because assignments are expressions, rather than statements, they can be used anywhere. For 

example, this is valid: 

if (a = 2) 

println "true" ; 

fi 

String/Vector Operations 

There are a number of other string/vector operators, summarized in this table: 

Function Description 

access(filename,[num|str]) return true if filename's mode is str or num 

cd(pathname) change to named directory 

cinclude(filename) include filename; return 0 if it does not exist 

exec(expression {, 

expression}) 

execute command line 

filepath(expression) return vector containing path name components 

getcwd() return current working directory path 

getenv(name) return value of environment variable name 

getopt([str[, optind]]) process options string 

include(filename) include filename; abort if filename does not exist 

index(str,expr) return index of first expr in str 

isatty(fileno) return true if fileno is a tty 

offset(indexable_object) return cursor offset in indexable_object 

ovl_exec() execute command line in overlaid memory 

319 of 457

putenv() alter value of environment variable 

read(indexable_object) return next token from indexable_object 

replace(str,old,new) return str with old replaced by new 

rindex(str,expr) return index of last expr in str 

strerror() return string corresponding to errno 

substr(expr,pos) return substring of expr starting at pos 

substr(expr,pos,len) return length len substring of expr starting at pos 

tail(indexable_object) return unread portion of indexable_object 

tempfile([dir_str,] 

pre_str) 

temporary file name 

tolower(expr) return expr in lowercase 

toupper(expr) return expr in uppercase 

Table 3: Summary of cc Functions 

access(filename, [mode]) 

returns true if the access mode of filename is the same as the supplied mode. The mode 

should be passed as a string composed of the characters r, w, x, or f (for read, write, 

execute, or file existence). If no mode is supplied, f is assumed. 

access("temp.af9","f") -- checks if temp.af9 exists 

access("temp.af9","rw") -- checks for read/write 

permission on temp.af9 

If the base operating system allows, mode can be passed as a number. This is non-portable, so 

you should use a string representation. 

cd(pathname) 

changes the current directory to the value of pathname. 

cinclude(filename) 

includes the specified file. No path search is performed. If filename is not an absolute path 

name, the current directory is searched. If the file does not exist, this function returns 0; 

otherwise, it returns 1. 

exec(expression {, expression}) 

is similar to the exec statement. The value of an exec expression is the exit status of the 

last command executed. This is an integer. 

filepath(expression) 

returns a vector whose components are the strings corresponding to the path name 

components of the string expression. The built-in variable DIRSEPSTR is used to determine 

320 of 457

the components of the path. 

getcwd() 

returns the current working directory path. 

getenv(name) 

returns the string value of the environment variable indicated by the string expression name. 

If the environment variable is not set, the null string "" is returned. 

getopt([optstr[, optind]]) 

processes an option string; this simplifies the business of writing scripts that take options. 

optstr is a format string listing each option character; if the option character is followed by a 

colon, the option takes an argument. For example, the format string "aei:o:u" specifies 

that the options a, e, i, o, and u are valid, and the colons show that both i and o require 

arguments. The option being processed is stored in a variable; if there is an argument, it is 

stored in the global variable OPTARG. 

optstr only needs to be specified on the first call. Subsequent calls to getopt() continue 

processing the same ARGV argument string. Here is a bit of code that sets flag variables for 

each option called: 

while (opt = getopt("dl:rtx")) do 

if (opt == "d" ) d_flag++; 

elif (opt == "l" ) 

l_flag++; 

l_arg = OPTARG; 

elif (opt == "r" ) r_flag++; 

elif (opt == "t" ) t_flag++; 

elif (opt == "x" ) x_flag++; 

fi 

done 

The getopt call does not remove items from the ARGV string, it just moves the OPTIND pointer 

through the ARGV vector. If you want to pass the tail of the argument string without the options, you 

can reset the value of ARGV with code like this: 

members = {}; 

for (i=OPTIND; ARGV{i}; i++) do 

members |= { ARGV[i] ); 

done 

ARGV = members; 

include(filename) 

321 of 457

includes the specified file. No path search is performed. If filename is not an absolute path 

name, the current directory is searched. If the file does not exist, the script aborts. 

Note: 

Expressions are compiled completely and then executed. As a result, if you use 

include in a function, the file is not included until an expression referencing the 

function is executed. 

index(expression, string-expression) 

returns the index of the first occurrence of string-expression in the expression If the first 

expression is a vector, it is first converted into a string. The index is 1-origin; a value of 0 is 

returned if the second expression is not a substring of the first. 

isatty(filenum\) 

returns true if filenum is a tty; filenum is an integer representing a file number. The values 

0, 1, and 2 represent standard input, standard output, and standard error, respectively. 

offset(indexable_object) 

returns the current stream offset in an indexable object. 

ovl_exec(expression {, expression}) 

constructs a command line in the same way, and then overlays cc with that command. cc 

exits with the exit code returned by that command. 

putenv(string) 

where string is a string expression of the form name=value assigns value to the environment 

variable indicated by the string expression name and adds that variable to the current 

environment. 

read(indexable_object) 

reads the next item from indexable_object and returns it. 

replace(string, old, new) 

returns string with all occurrences of the first character of the string old replaced with the first 

character of the string new. 

rindex(expression, string-expression) 

is similar to index but returns the index of the last occurrence. 

strerror() 

Returns the string that corresponds to the current value of errno. If errno is not set, 

returns a null string. 

322 of 457

substr(expression, position) 

returns the substring of the first string, starting at the position given by the second argument 

(an integer expression). Strings are 1-origin; however, for convenience, if the value of 

position is 0, substr returns the substring beginning at 1. If position is negative, it is taken 

to be an offset from the end of the string. For example: 

substr("hello",0) = substr("hello",1) -> "hello" 

substr("hello",length("hello")) -> "o" 

substr("hello",-3) -> "llo" 

substr("hello",-1) -> "o" 

substr may also take three arguments, as in: 

substr(expression, position, length) 

The length argument is an integer expression, giving the desired number of characters in 

the substring. If this value is negative, the substring is obtained by advancing to the 

indicated position, marking that the end, and then retreating by the specified amount. For 

example: 

substr("hello",0,1) = substr("hello",1,1) -> "h" 

substr("hello",-1,-3) -> "llo" 

tail(indexable_object) 

returns the unread portion of an indexable_object. 

tempfile([dir_str], pre) 

returns a string guaranteed to be an unused temporary file name in the directory specified 

by dir_str. If no dir_str is provided, then the directory specified by TMPDIR is used; if 

TMPDIR is not set, the system default is used (usually /tmp. If pre is not an empty string, it 

is taken as a prefix for the name of the temporary file. 

tolower(expression) 

returns the string expression with all uppercase characters translated to lowercase. 

toupper(expression) 

does the opposite translation. 

AVAILABILITY 




323 of 457





SEE ALSO 

Commands: 

cc 

324 of 457

diagnostics 

applicable to MKS Integrity Suite commands 

DESCRIPTION 

The exit status values for MKS Integrity Suite commands si, im, aa, integrity) can be used by 

event triggers for automating processes with Source Integrity or Integrity Manager. This reference 

page is provided as a guide to the exit status values you may see. 

DIAGNOSTICS 

Possible exit status values for MKS Integrity Suite commands are: 

0 

1 

2 

3 

4 

5 

6 


or 

No differences between the files being compared (using si diff). 

Command usage error. 

Command was canceled by user. This does not include cancellations using CTRL-c, which 

overrides this exit status value. In those cases, the return code will be 130. 

Invalid element in the selection for the command. 

Sandbox specified was ambiguous (using an si command). Command not executed. 

Unable to create or utilize the selection for the command. 

Unable to continue with the selection for the command because the program cannot find the 

next element. 

325 of 457

10 

16 

17 

19 

128 

130 

255 

SEE ALSO 

Connection failed: a network error caused the command to terminate. 

diff compared the files and found them to be different (using si diff). 

Failure due to any of the following (using si diff): 

❍ invalid command line argument 

❍ cannot open one of the input files 

❍ out of memory 

❍ read error on one of the input files 

❍ more than LINE_MAX characters between newlines 

At least one of the files is a binary file containing embedded NUL (\0) bytes (using 

si diff). 

General command failure. 

Command was canceled by the user using CTRL-c. 

Unknown exception or error code. 


ACL, options, preferences 

326 of 457

NAME 

envvar — standard environment variables 

SYNOPSIS 

export NAME=value 

set NAME=value 

echo $NAME 

DESCRIPTION 

envvar -- Miscellaneous Information 

When a process is executed, it inherits a set of strings called the environment. It is conventional for 

these strings to have the form: 

NAME=value 

The export command built into the MKS KornShell can be used to set the variable NAME into the 

environment of every child process. The set command built into command.com or cmd.exe does 

the same. The echo command prints the value of environment variable NAME inside the MKS 

KornShell. 

Note: 

The shell maintains additional shell variables that are not exported to child processes; 

because these variables are not passed on, they are not environment variables. 

The following environment variables are used throughout MKS Toolkit: 

COLUMNS 

If you set this variable to a numeric value, various commands use its value as the width of 

the output device in columns. This overrides the default. 

COMSPEC 

The value of this variable must point to the standard command interpreter (command.com or 

cmd.exe), if you want to use that command interpreter in any way. This variable is called 

ComSpec under Windows NT/2000/XP/2003. 

ENV 

327 of 457

The value of this variable is the name of a file of MKS KornShell commands, or else be null. 

When the MKS KornShell is invoked, the file named by ENV is executed before the MKS 

KornShell does anything else. Thus your ENV file may contain definitions of aliases, shell 

functions, and son on that may be used by shell scripts. Note that your ENV file is executed, 

whether or not the MKS KornShell is invoked as a login shell. This differs from older 

releases of the MKS KornShell. 

HASHBANG 

If this variable is set then the #! feature of the MKS KornShell is enabled. 

HOME 

This variable is set by the shell's default startup files. It contains the name of your home 

directory. Your home directory is the default directory for the cd command built into the MKS 

KornShell. 

LINES 

If you set this variable to a numeric value, various commands use its value as the number of 

lines available on the output device. This overrides the default. 

LOGNAME 

This variable is set by the shell's default startup files. It holds the user name of the current 

user. 

MAILER 

For commands that send mail, this variable points at a mail delivery program. If this variable 

is not set, then the default mailer, mailx is invoked. 

PATH 

This variable is set to a default value when you start the MKS KornShell. Normally, it is also 

set in your profile file. It lists the directories that are to be searched to find commands, as 

described in sh. 

ROOTDIR 

Because Windows systems have a multi-device file system, it is necessary to provide the 

location of the standard root directory for system files (for example, /etc/profile.ksh 

and /tmp). This variable contains a device name and possibly a directory where such files 

are found. 

SHELL 

This variable contains the full path name of the current shell. Note that if SHELL is not 

defined, all commands that require the full path name of the current shell use the contents of 

the environment variable COMSPEC. 

328 of 457

TERM 

This variable contains the terminal type. 

TK_NTLINKS_OFF 

MKS Toolkit supports hard links under Windows NT/2000/XP/2003 on NTFS file systems. 

There is a slight loss of performance for this support. If you do not require hard link support 

then you should set and export the environment variable TK_NTLINKS_OFF to disable this 

support. 

TK_NTSECURITYINFO_OFF 

MKS Toolkit supports Windows NT/2000/XP/2003 security information on NTFS file 

systems. There is a slight loss of performance for this support. If you do not require any 

security information then you should set and export the environment variable 

TK_NTSECURITYINFO_OFF to disable this feature. 

TK_NTSECURITYINFO_SID_TERSE 

Under Windows NT/2000/XP/2003, when using ls with the -l option, files having an 

associated SID, whose name cannot be determined, display the value of the SID instead. 

SID values are usually very large. You should set and export the 

TK_NTSECURITYINFO_SID_TERSE environment variable. This causes all SID values to 

be shortened by replacing all the subauthority values, except the last one, by the string "-...- 

". 

TK_PERL_USE_COMSPEC 

When set, this environment variable causes perl to use the contents of the environment 

variable COMSPEC as the full path name of the current shell, whether or not the 

environment variable SHELL is set. 

TMPDIR 

By default, MKS Toolkit commands store temporary files under /tmp. To use a different 

directory for temporary files, set TMPDIR to the name of the directory you want to use. 

TZ 

Commands that print times (and dates) use this variable to determine the time zone. If the 

TZ variable is left undefined, the operating system's current time zone setting is used. See 

timezone for details. On Windows, the MKS Toolkit makes use of the built-in timezone 

support, and you should not set the TZ environment variable. 

PORTABILITY 

The standard names on Windows systems are a superset of those used by UNIX programs, with 

COMSPEC (ComSpec under Windows NT/2000/XP/2003), ROOTDIR and TK_* being the major 

329 of 457

additions. 

AVAILABILITY 











SEE ALSO 

Commands: 

cd, env, ls, sh 


timezone 

330 of 457

NAME 

makefile — format of MKS Make file 

DESCRIPTION 

makefile -- Miscellaneous Information 

This reference page offers a summary of the syntax of a makefile's contents, using a style similar 

to BNF (Backus Naur Form). Items enclosed in [ ] are optional, while items enclosed in { } can 

appear zero or more times. 

makefile 

→ { makefile-line } 

makefile-line 

→ macro-definition 

→ target-definition 

→ attribute-definition 

→ conditional 

A line is a possibly empty sequence of characters, terminated by a nonescaped newline character; 

that is, one not immediately preceded by a backslash (\). A line can be extended over several 

input lines by placing a \ at the end of each line to be continued. 

A comment begins with a # and extends to the end of the line. In the following, an expression is 

defined as 

expression 

→ string 

→ string == string 

→ string != string 

where string is defined as a literal sequence of characters, or the sequence of characters resulting 

from the expansion of a macro. 

A conditional is defined as 

conditional → 

.IF expression 

makefile 

{ .ELSIF expression 

331 of 457

makefile 

} 

[ .ELSE 

makefile 

] 

.END 

A rule-definition is defined as 

rule-definition → 

targets [ attributes ] op [prerequisites] [ ; recipe ] 

recipe 

targets → 

target { target } 

A target may be a special-target. 

Any number of attributes may follow a target in a rule-definition. 

attribute 

→ .IGNORE 

→ .SILENT 

→ .PRECIOUS 

→ .LIBRARY 

→ .PROLOG 

→ .EPILOG 

→ .SETDIR=path 

An attribute-definition is like a rule-definition, except that a recipe is not allowed. An attributedefinition 

is given as 

attribute-definition 

→ attribute { attribute } : targets 

The op defines the type of rule. 

op → : 

→ :: 

→ :^ 

→ :! 

→ :- 

→ :| 

332 of 457

The prerequisites are a list (possibly empty) of targets that must be brought up-to-date before 

making the current target. The prerequisites may optionally be followed by a semicolon (;) and a 

recipe. 

A recipe normally follows; it consists of a number of lines, all starting with at least one tab 

character, or a group-recipe, which is written between brackets ([ ]). 

recipe 

→ { [+@-] line } 

→ [[+@-]lines] 

A special-target is a keyword that is given as a target in a rule-definition. The following special 

targets are allowed: 

special-target 

→ .BRACEEXPAND 

→ .ERROR 

→ .EXPORT 

→ .GROUPEPILOG 

→ .GROUPPROLOG 

→ .IMPORT 

→ .INCLUDE 

→ .INCLUDEDIRS 

→ .MAKEFILES 

→ .NOAUTODEPEND 

→ .REMOVE 

→ .SOURCE 

→ .SOURCE.suffix 

→ .SUFFIXES 

→ .POSIX 

A macro-definition is recognized as a string followed by an = character. There are three forms of 

macros: 

macro = string 

assign string to macro 

macro := string 

expand macro definitions string, then assign 

macro += string 

append string to end of macro 

333 of 457

If string is empty, macro is assigned the null string (unless you use the += operator; in this case, 

the macros contents are not touched). White space on either side of the =, :=, or += is ignored. 

Macros are expanded by $(macro) or ${macro}. If a macro name is a single letter, it can also be 

expanded by $n, where n is the name. 

If the .BRACEEXPAND special target is set, make expands a token sequence (separated by white 

space) prepending a prefix string and appending a suffix string to each token: 

string1{ token-list }string2 

Future versions of MKS Make may not support this obsolescent feature. 

A macro can also be modified as it is expanded. The syntax for this is 

$(macro {:modifier}) 

where any number of modifiers can be supplied, separated by :. 

modifier 

→b 

→d 

→f 

→l 

→ s/string/new_string/ 

→ suffix_string=new_suffix_string 

→ t"string" 

→u 

→^"string" 

→+"string" 

The :s modifier is a substitute operator; occurrences of the given pattern that are matched are 

replaced by the indicated value. The :t modifier tokenizes the macro string definition, placing the 

given string between each name in the indicated string. That string may contain the following 

escape sequences: 

\" → " 

\\ → \ 

\a → alert or 

\b → 

\f → 

\n → 

334 of 457

\r → 

\t → 

\v → 

The :u modifier maps all characters in the expansion to uppercase. 

The :l modifier maps all characters in the expansion to lowercase. 

The :^ modifier adds a prefix to all of the tokens in the expanded macro. 

The :+ modifier adds a suffix to all of the tokens in the expanded macro. 

A number of built-in macros are defined by MKS Make. 

$@ full target name 

$$@ dynamic expansion of $@ 

$% full target name, or name of archive library 

$$% dynamic expansion of $% 

$* $@ without suffix; same as $(@:db) 

$$* dynamic expansion of $* 

$> library name for current target (library member) 

$$> dynamic expansion of $> 

$? all recently changed prerequisites 

$< in normal rules, those prerequisites prompting 

execution of current rule; in inference rules, the 

prerequisite of the current rule 

$& all prerequisites 

$^ prerequisites in current rule 

MKS Make also uses control-macros, whose value is either maintained by make, or used to control 

the corresponding attribute. 

control-macros 

→ DIRSEPSTR 

→ .EPILOG 

→ GROUPFLAGS 

→ GROUPSHELL 

→ GROUPSUFFIX 

→ .IGNORE 

→ INCDEPTH 

→ MAKE 

→ MAKECMD 

335 of 457

→ MAKEDIR 

→ MAKEFLAGS 

→ MAKESTARTUP 

→ MFLAGS 

→ NULL 

→ .PRECIOUS 

→ .PROLOG 

→ PWD 

→ SHELL 

→ SHELLFLAGS 

→ SHELLMETAS 

→ .SILENT 

For example, the .SILENT macro is like the .SILENT attribute, except that using the macro 

assigns the .SILENT attribute to all targets. 

AVAILABILITY 







SEE ALSO 

Commands: 

make 

336 of 457

options 

applicable to MKS Integrity Suite commands 

DESCRIPTION 

Some MKS Integrity Suite commands (si, im, aa, integrity) share general options, while all take certain universal options. This 

reference page is provided as a guide to these common options. 

Source Integrity: Specifying Members, Sandboxes and Projects 

There are three types of Source Integrity commands, and therefore the way you specify the member varies: 

1. Some commands can only be executed on members in the context of a sandbox, because they manipulate the member's working file. 

These are noted as requiring a sandbox member..., such as si ci, si co, and si merge. These take a sandbox member, and you 

may not perform the operation against a project member. If you try to specify a project for these commands, you will see an error 

message. 

2. Other commands do not manipulate a member's working file, and therefore can be performed directly in the context of a project. If you 

specify a sandbox, it is simply used as a pointer to find the project itself. The fact that you specify the sandbox is only incidental. 

These are noted as requiring a project member..., and most of the commands that say member... fall into this category; for example, 

si updaterevision, si updatearchive, and si addlabel. 

3. There are also some commands that perform differently depending on whether they are given a sandbox or a project. Examples for 

this would be si diff and si edit. 

You can explicitly specify either -P or -S options for most commands. For - 

P you must specify a project or subproject, the -P option does not accept the filename of a sandbox. For - 

S you must specify a sandbox or subsandbox, -S does not accept the filename of a project. 

Source Integrity also allows for implicit sandbox selection. This means that you can use commands without explicitly specifying a - 

S sandbox option, and Source Integrity determines the sandbox to operate on based on the directory you're working in. 

For example, suppose you are working in the directory C:\test\sbx\sub1\sub2, and suppose you have a sandbox only in the \sbx 

directory. Using the -S option to explicitly specify the sandbox, you might enter the following to check in a file: 

si ci -S c:\test\sbx\project.pj header.c 

Using implicit sandbox location to check in a file, you might enter: 

si ci header.c 

If the sandbox is not specified explicitly through - 

S, Source Integrity tries to locate one by starting in the current working directory and seeing if there is a sandbox registered in that directory. 

If there isn't, it searches up the directory tree until it either finds one, or until it reaches the root of the drive. In the example provided, Source 

Integrity first determines there is no sandbox in \sub2, then \sub1, then finds the sandbox in \sbx and uses that sandbox. 

Now suppose you have sandboxes in each of \sbx, \sub1, and \sub2. This implicit sandbox selection allows you to work with multiple 

sandboxes in one command line entry, and without having to explicitly specify lengthy locations for each one. If you're working in the 

C:\test\sbx directory and decide to check in files to each sandbox, for example, you might enter: 

si ci header.c sub1\comp.c sub1\sub2\img.c 

This checks in the file header.c to the sandbox at C:\test\sbx , checks in the file comp.c to the sandbox at C:\test\sbx\sub1, and 

checks in the file img.c to the sandbox at C:\test\sbx\sub1\sub2. 

A requirement for implicit sandbox location to operate correctly is that there can be no more than one sandbox (or subsandbox) registered in 

a single directory. If you create two or more sandboxes in the same directory, the implicit sandbox location algorithm cannot unambiguously 

determine which sandbox to use in that directory, and it prompts you to clarify by specifying the name of the sandbox that you want to use in 

that case. In general, you shouldn't create multiple sandboxes in the same directory. 

Note: 

Certain si commands do not operate on Build sandboxes, which are created as read-only for the purpose of building a programming 

artifact. Using inappropriate commands with a Build sandbox causes error messages to appear. 

337 of 457

General Options 

Some MKS Integrity Suite commands share the following general options. 


identifies the development path of a variant project. This is always paired with a -P project or -project=project. 

This is a label that was associated with a branch of the project by si createdevpath. It is mutually exclusive 

with the -S sandbox or --sandbox=sandbox option since a sandbox remembers any devpath. 

Note: 

Paths that include spaces must be enclosed by quotes. Additionally, the following characters may not be used in a 

development path: \n, \r, \t, :, [', '], #. 

--filter=filteroptions 

allows you to select members for all commands that take a list of members, using filteroptions, which can be one or more of the 

following: 

archiveshared 

selects members that share another member's archive. This option is valid only with the database repository. 

attribute:name[=value] 

selects members based on an attribute name and, optionally, value. 

changed [:working|:sync|:newer|:size|:missing|:newmem|:all] 

selects changed members based on: changes to working files, those that are out of sync with the project, those where a newer 

revision exists in the project, or based on all changes. 

rule [:memberrevdiffers|:defined|:invalid] 

selects members based on a revision rule filter. :memberrevdiffers selects all members for which the rule does not match 

the member revision. :defined selects all members with a revision rule. :invalid selects all members for which the rule 

does not expand to any existing revision. 

file:expression 

selects members with a specific file name. This allows you to specify wild cards for file naming, such as the asterisk (*) to 

match any number of characters, and the question mark (?) to match a single character. For example, *.java or 

*RB.properties would be valid expressions. 

frozen 

selects frozen members. 

label[:name] 

selects any member whose member revision has the specified label. 

anylabel[:name] 

selects any member that contains a revision that has the specified label. 

locked[:name] 

selects all locked members or those locked by a particular user. 

state[:name] 

selects members based on state. 

format[:text|:binary] 

selects members based on storage format. 

workingbranch 

selects members where the working file is on a branch from a given development path that is not the trunk development path. 

Note: This filter applies only to sandboxes. 

deferred[:add|:addfromarchive|:checkin|:drop|:import|:move|:rename|:updaterevision|:all] 

selects deferred members based on: add, addfromarchive, checkin, drop, import, move, rename, updaterevision, or all 

operations. 

memberonbranch 

shows only members that are off the main development trunk. 

unresolvedmerges 

selects members affected by unresolved merges. 

pending[:add|:addfromarchive|:drop|:import|:movememberfrom|:movememberto|:renamefrom|:renameto|:update|:updaterevision|:all] 

selects pending members based on add, addfromarchive, drop, import, movememberfrom, movememberto, renamefrom, 

renameto, update, updaterevision, or all operations. 

workinprogress 

combines the deferred (all), locked (all), and changed (all) filters to select members that are considered work in progress. 

sparsecontents 

shows only existing working files and deferred operations in a sparse sandbox. 

338 of 457

Using commas between the filteroptions serves to build logical "OR" statements between them, allowing you to create powerful filters. 

You may also specify multiple -filter=filteroptions 

on the command line, which effectively creates logical "AND" statements between them. 

For example, you can resynchronize all modified JAVA files through: 

si resync --filter=changed --filter=file:*.java 

or you can resynchronize all files with label a or b through: 

si resync --filter=label:a,label:b 

You can also negate a filter using the ! character. 

For example, you can check out all JAVA files that are not labelled Beta by typing: 

si co --filter=file:*.java --filter=!label:Beta 

--hostname=server 

identifies the name of the host server where the Integrity Server is located. 

--password=password 

identifies the password to use for connecting to the Integrity Server. 

--port=number 

identifies the port on the host server where the Integrity Server is located. 

-P project 

--project=project 

specifies the location of a project. This option is mutually exclusive with -S sandbox|--sandbox =sandbox. 

Note: 

Locations that include spaces must be enclosed by quotes. 


identifies a particular revision of a project. This option is always paired with -P project|project=project, 

and is mutually exclusive with -devpath. 

It is available on all project-based commands allowing you to specify the revision of the build project you want to work with. 

-R 


controls whether to recursively apply this command to any subprojects; used in all commands which take a list of members. 

-r rev 

--revision=rev 

uses a specified revision for the member. rev can be a valid revision number or a label. You may also facilitate automation with 

special keyword identifiers, specified using a colon (:) prefix (except for the state keyword). Acceptable identifiers are: 

:head 

identifies the head revision. 

:member 

identifies the member revision. 

:locked 

identifies locked revisions. 

:master 

identifies the member revision in the master project. This option is only applicable to variant projects. 

:time:timestamp 

uses the most recent revision on any branch at the specified timestamp. For example, -rtime:December 22, 2004 

3:33:34 PM GMT-05:00. Source Integrity recognizes all current timezones whatever your locale (country), for example, 

CEST, CET, EDT, PST, or GMT+/-hours:minutes. The following examples illustrate North American and German timestamps 

recognized by Source Integrity: 

Example 1: US GMT -5 (where E is the day of the week, M is the month, d is the numerical day of the month, y is the year, h is 

the time in hours, m is the time in minutes, s is the time in seconds, a is Greenwhich Mean Time (GMT), z is the timezone 

difference from Greenwhich Mean Time. 

05:00 

EEEE, MMMM d, yyyy h:mm:ss a z | Wednesday, April 28, 2004 3:33:45 AM GMT- 

EEEE, MMMM d, yyyy h:mm:ss a z | Wednesday, April 28, 2004 3:33:45 AM GMT- 

339 of 457

05:00 

EEEE, MMMM d, yyyy h:mm:ss a | Wednesday, April 28, 2004 3:33:45 AM 

EEEE, MMMM d, yyyy h:mm a | Wednesday, April 28, 2004 3:33 AM 

MMMM d, yyyy h:mm:ss a z | April 28, 2004 3:33:45 AM GMT-05:00 

MMMM d, yyyy h:mm:ss a z | April 28, 2004 3:33:45 AM GMT-05:00 

MMMM d, yyyy h:mm:ss a | April 28, 2004 3:33:45 AM 

MMMM d, yyyy h:mm a | April 28, 2004 3:33 AM 

MMM d, yyyy h:mm:ss a z | Apr 28, 2004 3:33:45 AM GMT-05:00 

MMM d, yyyy h:mm:ss a z | Apr 28, 2004 3:33:45 AM GMT-05:00 

MMM d, yyyy h:mm:ss a | Apr 28, 2004 3:33:45 AM 

MMM d, yyyy h:mm a | Apr 28, 2004 3:33 AM 

M/d/yy h:mm:ss a z | 4/28/04 3:33:45 AM GMT-05:00 

M/d/yy h:mm:ss a z | 4/28/04 3:33:45 AM GMT-05:00 

M/d/yy h:mm:ss a | 4/28/04 3:33:45 AM 

M/d/yy h:mm a | 4/28/04 3:33 AM 

h:mm:ss a z | 3:33:45 AM GMT-05:00 

h:mm:ss a z | 3:33:45 AM GMT-05:00 

h:mm:ss a | 3:33:45 AM 

h:mm a | 3:33 AM 

EEEE, MMMM d, yyyy | Wednesday, April 28, 2004 

MMMM d, yyyy | April 28, 2004 

MMM d, yyyy | Apr 28, 2004 

M/d/yy | 4/28/04 

MMM d, yyyy - h:mm:ss a | Apr 28, 2004 - 3:33:45 AM 

MMM d, yyyy - h:mm a | Apr 28, 2004 - 3:33 AM 

Example 2: Germany CEST (where E is the day of the week, M is the month, d is the numerical day of the month, y is the year, H is 

the time in hours, m is the time in minutes, s is the time in seconds, Uhr 'z is Central European Summer Time (CEST). 

EEEE, d. MMMM yyyy H.mm' Uhr 'z | Montag, 26. Juli 2004 22.26 Uhr CEST 

EEEE, d. MMMM yyyy HH:mm:ss z | Montag, 26. Juli 2004 22:26:29 CEST 

EEEE, d. MMMM yyyy HH:mm:ss | Montag, 26. Juli 2004 22:26:29 

EEEE, d. MMMM yyyy HH:mm | Montag, 26. Juli 2004 22:26 

d. MMMM yyyy H.mm' Uhr 'z | 26. Juli 2004 22.26 Uhr CEST 

d. MMMM yyyy HH:mm:ss z | 26. Juli 2004 22:26:29 CEST 

d. MMMM yyyy HH:mm:ss | 26. Juli 2004 22:26:29 

d. MMMM yyyy HH:mm | 26. Juli 2004 22:26 

dd.MM.yyyy H.mm' Uhr 'z | 26.07.2004 22.26 Uhr CEST 

dd.MM.yyyy HH:mm:ss z | 26.07.2004 22:26:29 CEST 

dd.MM.yyyy HH:mm:ss | 26.07.2004 22:26:29 

dd.MM.yyyy HH:mm | 26.07.2004 22:26 

dd.MM.yy H.mm' Uhr 'z | 26.07.04 22.26 Uhr CEST 

dd.MM.yy HH:mm:ss z | 26.07.04 22:26:29 CEST 

dd.MM.yy HH:mm:ss | 26.07.04 22:26:29 

dd.MM.yy HH:mm | 26.07.04 22:26 

H.mm' Uhr 'z | 22.26 Uhr CEST 

HH:mm:ss z | 22:26:29 CEST 

HH:mm:ss | 22:26:29 

HH:mm | 22:26 

EEEE, d. MMMM yyyy | Montag, 26. Juli 2004 

d. MMMM yyyy | 26. Juli 2004 

dd.MM.yyyy | 26.07.2004 

dd.MM.yy | 26.07.04 

MMM d, yyyy - h:mm:ss a | Jul 26, 2004 - 10:26:29 PM 

MMM d, yyyy - h:mm a | Jul 26, 2004 - 10:26 PM 

:timeonbranch:timestamp@branchnumber 

uses the most recent revision on a specific branch at a specific timestamp. -rtimeonbranch:timestamp uses the most 

recent revision on the branch where the member revision currently resides. For example, -rtimeonbranch:December 22, 

2004 3:33:34 PM GMT-05:00. -rtimeonbranch:timestamp@branchnumber uses the most recent revision on the 

specified branch at the specified timestamp. For example, -rtimeonbranch:December 22, 2004 3:33:34 PM GMT- 

05:00@1.5.1.1. Source Integrity recognizes all current timezones whatever your locale (country), for example, CEST, CET, 

340 of 457

EDT, PST, or GMT+/-hours:minutes. For timestamp examples, see the :time:timestamp option. 

Note: Updating a revision by timestamp makes the most recent revision at the specified timestamp the member revision. 

:memberbranchtip 

identifies the tip revision on the member revision branch. 

:working 

identifies the working revision. 

:trunktip 

identifies the tip revision on the trunk. 

state:statename 

identifies the state, for example, Beta. This option is useful when you want to select revisions in a project that are in a specific 

state. 

For each project member, Source Integrity searches from the member revision on the development path to the root of the 

archive to find a revision that corresponds to the specified state. If the member revision is on a branch, Source Integrity starts 

from the tip revision and searches to the root of the archive; other branches in the archive are not searched. If no revision on 

the development path matches the specified state, the command fails, stating "Revision does not exist." 

devpath: devpathname 

identifies the development path. This keyword only operates on member commands. 

build: revisionnumber 

identifies the build revision number, which must be a valid project revision number or project label in which a given member is 

contained. Must specify a registered project. This keyword only operates on member commands. 

:rule 

identifies a rule defined with the si setmemberrule command. 

link:p=project[::d=devpath][::m=member][::recurse] [::b=buildrevnumber] 

allows you to set the member revision to whatever is the member revision for the corresponding member in a specific external 

project configuration (normal, variant, build). Links the project that the member belongs to (the target project) with the master 

project where: 

project is the master project 

devpath is the development path for the master project 

member is a member in the target project. If not provided, the project is searched for a member with the same backing archive. 

If recurse is specified, the search is recursive throughout the subprojects. There must be exactly one backing archive for each 

member. 

A possible application is to update all members to the same revision, even if they don't have the same backing archive. 

-S sandbox 

--sandbox=sandbox 

specifies the location of a sandbox. In some cases, the commands that take this option do something with the sandbox contents 

themselves. In other cases, specifying the sandbox location is simply a way to locate, or "point to", the corresponding project file. This 

option is mutually exclusive with -P project|--project =project. 

Note: 

Locations that include spaces must be enclosed by quotes. 

--user=name 

identifies the user to use for connecting to the Integrity Server. 

Universal Options 

The following universal options apply to all MKS Integrity Suite commands. 

--[no]batch 

controls batch mode. Batch mode forces the application to process commands without prompting for responses. 

--cwd=directory 

acts as if the command is executed in the specified directory. In particular, any files and members in the selection are treated as being 

relative to that directory. 

Suppose you are working in the c:\sandbox directory and you want to issue the check out command so that the implicit sandbox 

selection will work in a subdirectory, rather than having to specify the complete path for subdirectory sandbox names. You could use 

the --cwd option to do this, for example: 

si co --cwd=./demoapp/controls demoappctrl.c 

341 of 457

makes Source Integrity work in the c:\sandbox\demoapp\controls directory and follows implicit sandbox selection rules from 

there to find the appropriate sandbox, then checks out the demoappctrl.c file. 

-F file 

--selectionFile=file 

provides an alternative way to specify the selection. The specified file is a text file containing a list of file names, members, projects, or 

sandboxes, one per line. The command operates on all the listed files. 

Note: 

Be careful to avoid duplications. In some cases if a file, member, project or sandbox is listed twice in the file, the command may 

report an error. 

--forceConfirm=[yes|no] 

-N 

--no 

-Y 

--yes 

controls the responses of either "yes" or "no" to all prompts. Specifying "yes" or "no" can be an easy way to accomplish the same 

thing as specifying other command options with [no|confirm] prefixes, for example the 

--[no|confirm]overwriteChanged option in the si co, si resync, and si revert commands. Specifying 

--yes or --no accomplishes the same thing for --overwriteChanged and -nooverwriteChanged, 

but further responds "yes" or "no" to all other questions asked. 

Note: 

Be careful to use specific options if you want variations in your responses to prompts. The 

--yes and -no 

options in particular are wide-ranging types of responses and should be used only in rare circumstances. 

-g 

--gui 

allows user interaction to happen through the GUI (graphical user interface). 

--width 

controls the width in pixels of the graphical user interface. 

--height 

controls the height in pixels of the graphical user interface. 

-x 

specifies the x location in pixels of the graphical user interface window. 

-y 

specifies the y location in pixels of the graphical user interface window. 

--quiet 

controls the status display to silence most information messages. 

--settingsUI=[gui|default] 

controls the GUI for command options. 

--status=[none|gui|default] 

controls the status display. 

-? 

--usage 

shows usage for the command. 

DIAGNOSTICS 


SEE ALSO 


ACL, diagnostics, preferences 

342 of 457

preferences 

preferences applicable to MKS Integrity Suite setprefs and viewprefs commands 

DESCRIPTION 

The setprefs and viewprefs commands refer to the same group of commands and preference 

keys for the MKS Integrity Suite component you are configuring (si, im, aa, integrity). This 

reference page is provided as a guide to the preferences you can configure. To see each 

component's specific keys, simply append the command to the viewprefs command. For 

example, 

si viewprefs --command=co 

displays the following output: 

co: mergeType 

co: onMergeConflict 

co: allowImplicitIdentification 

co: branchIfVariant 

co: changePackageID 

co: cwd 

co: filter 

co: forceBranch 

co: forceConfirm 

co: includeFormers 

co: issueID 

co: keywordExpand 

co: lock 

co: merge 

co: onLock 

co: overwriteIfChanged 

co: overwriteIfUnchanged 

co: recurse 

co: restoreTimestamp 

co: revision 

co: sandboxName 

co: selectionFile 

co: updateMemberRev 

co: command.batchMode 

co: sandbox.allowProjectSelection 

co: sandbox.allowSandboxSelection 

co: server.credential 

co: server.hostname 

343 of 457

co: server.port 

co: server.user 

co: si.lastUsedChangePackageID 

co: socksProxyHost 

co: socksProxyPort 

co: status.popupDelay 

co: swing.lookAndFeel 

Preference Keys 

The preference keys you can specify for the above commands are often similar, and some are 

global preferences such that when you change it for one command, it changes for all. The following 

are some common preference keys: 

allowImplicitIdentification 

controls whether to allow the implicit identification and selection of sandboxes. This means 

that you can use commands without explicitly specifying a -S sandbox option, and Source 

Integrity determines the sandbox to operate on based on the directory you're working in. 

Valid values are true or false. 

cwd 

identifies a working directory for the command. In particular, any relative files and members 

in the selection are treated as being in that directory. 

command.batchMode 

a global key that controls batch mode. Batch mode forces the application to process 

commands without prompting for responses. Valid values are false, true. 

developmentPath 

specifies a particular development path to use with the command all the time. 

filter 

specifies a filter to use with the command all the time. 

forceConfirm 

specifies whether to force the application to request confirmation for the particular 


includeFormers 

specifies whether to include members that have been dropped from the project. 

projectName 

specifies a particular Source Integrity project to work with all the time. 

projectRevision 

specifies a particular Source Integrity project revision to work with all the time. 

recurse 

controls whether to recurse into subprojects. 

sandbox.allowProjectSelection 

a global key that controls whether to allow Source Integrity project selection. Valid values 

are false, true. 

sandbox.allowSandboxSelection 

a global key that controls whether to allow sandbox selection. Valid values are false, true. 

344 of 457

sandboxName 

specifies a particular sandbox to be used all the time. 

selectionFile 

specifies a file that lists member files to work with. 

server.credential 

a global key that identifies the credential, or password, for logging into the Integrity Server. 

server.hostname 

a global key that identifies the hostname for the Integrity Server. 

server.port 

a global key that identifies the port for the Integrity Server. 

server.user 

a global key that identifies the user name for logging into the Integrity Server. 

socksProxyHost 

a global key that identifies the SOCKS proxy host. 

socksProxyPort 

a global key that identifies the SOCKS proxy port. 

status.popupDelay 

a global key that controls the duration, in milliseconds (ms), that the commands status 

appears in the graphical user interface or the command line interface. 

swing.lookAndFeel 

a global key that controls the "look and feel" appearance of the graphical user interface. 

Valid values are System, Windows, Motif, Metal. 

SEE ALSO 


diagnostics, options 

345 of 457

csedit 

MKS Source Integrity editing facilities for descriptions and log messages 

DESCRIPTION 

Whenever MKS Source Integrity asks you to enter a description or log message, you may make 

use of editing commands to help you enter the message. Editing commands must be on a 

separate line and the first character of the line must be a tilde ~ character. Here are the recognized 

commands: 

~? 

Displays a summary of editing commands. 

~d 

Restore message from dead.let file. 

~e 

Writes the current message to a temporary file and invokes a text editor to edit that file. The 

name of the editor is taken from the EDITOR environment variable. If there is no such 

variable, ed is used. When you are finished editing the message, write it back out to the 

temporary file and quit the editor. You return to MKS Source Integrity. 

~p 

Displays the current text of the message. 

~q 

Copies the current message to a file named dead.let and quits. 

~r filename 

Reads the contents of the given file and appends them to the current message. 

~v 

Similar to ~e, except that it invokes the visual editor identified by the VISUAL environment 

variable. The default is vi. (You can only use vi if you have a UNIX system or the MKS 

Toolkit.) 

~w filename 

Writes the current message to the specified file. 

~! command 

Executes the given system command. 

If a line begins with a tilde, MKS Source Integrity assumes it is an editing command. If you want to 

enter a text line that begins with a tilde, type two, as in 

~~ This line begins with a single tilde. 

EXAMPLES 

346 of 457

These are the changes I have made: 

~r changes 

. 

reads in text from a file named changes and adds that text to the message being composed. The 

period (.) to mark the end of the message is still required. 


The MKS Source Integrity editing facilities use the following environment variables: 

EDITOR 

contains the name of the editor invoked by the ~e command. 

VISUAL 

contains the name of the editor invoked by the ~v command. 

PORTABILITY 

These facilities are extensions to traditional implementations of RCS and are non-portable. 

SEE ALSO 

Commands: 

si ci 

347 of 457

NAME 

ar — create and maintain library archives 

SYNOPSIS 

ar 

ar -d [-Ilv] archive member ... 

ar -m [-abIilsv] [posname] archive member ... 

ar -p [-Ilsv] archive [member ...] 

ar -q [-clsv] [-F format] archive member ... 

ar -r [-abcIilsuv] [-F format] [posname] archive member ... 

ar -t [-Ilsv] archive [member ...] 

ar -u [-abcIilsv] [-F format] [posname] archive member ... 

ar -x [-CIlsTv] archive [member ...] 

DESCRIPTION 

ar creates and maintains file archives. You can use ar to 

● create a new archive 

● add members to an existing archive 

● delete members from an archive 

● extract members from an archive 

● print a table of contents for an archive 

● rearrange the members of an existing archive 

● display the contents of an archive member 

These libraries may be in Intel Object Module Format (OMF) or Common Object File Format 

(COFF). On Windows systems, ar defaults to OMF format when creating a new library. 

This implementation takes UNIX-compatible options and arguments, but works with libraries in 

either the OMF format or the COFF format. ar tries to deduce the format of an existing archive; the 

default for a new library is OMF format. You may specify the format of a new library with the -F 

option. Only valid OMF or COFF .obj files may be members of a library. 

ar identifies each member in the archive by the final component (basename) of its file name. 

When adding a file to an archive, you can use the full path name, but when storing the member or 

348 of 457

comparing a member name, ar uses only the final component of the name. 

Options 

ar accepts the following options that represent its main functions: 

-d 

-m 

-p 

-q 

-r 

-t 

-x 

deletes each named member from the archive and regenerates the symbol table. 

moves the named archive member in the archive. You indicate the new position for the 

member with -a, -b, or -i and posname; if you do not specify a location, ar moves the 

member to the end of the archive. 

displays each specified member on the standard output. If you do not specify any members, 

ar displays all members. 

quickly appends the specified file to the archive. ar does not check to see if file is already a 

member of the archive. 

replaces or adds file to archive. If archive does not exist, ar creates it and prints a message. 

When ar replaces an existing member, it does not change the archive order. If file is not 

replacing a member, ar adds it to the end of the archive (unless you specify -a, -b, or -i). 

This option regenerates the symbol table. 

displays a table of contents that lists member or every member if you do not specify a 

particular member. ar displays a diagnostic for each member that it cannot find. Normally, 

ar displays only the member's name, but with the verbose (-v) option, ar displays more 

information about archive members using a format similar to ls -l. 

extracts each specified member from the archive and copies it to a file. If you specify 

member as a full path name, ar copies it to that path name. If you do not specify a member, 

ar extracts all members. The archive remains unchanged. 

The following options modify the behavior of the main functions: 

-a 

places file in archive after the member specified by posname. If you do not specify a 

349 of 457

-b 

-C 

-c 

member, ar adds file to the end of the archive. 

places file in archive before the member specified by posname. If you do not specify 

posname, ar adds file to the beginning of the archive. 

prevents ar from overwriting existing files with extracted files. You can only specify this 

option when extracting files with the -x option. 

suppresses the message ar normally prints when it creates a new archive file. You can only 

use this in conjunction with the -r and -q options. 

-F format 

specifies the archive format to be used by a new archive. Valid formats are omf and coff. 

You can only use this option when creating a new archive with the -r option or the -q 

option. 

-I 

-i 

-l 

-s 

-T 

When no format for a new library is specified, ar creates the new library using the format 

(OMF or COFF) of the first .obj file specified on the command line. If no .obj files exist on 

the command line, the library is created using the OMF format. 

ignores the case of letters when searching the archive for specified member names. 

Normally, the case is significant. 

inserts the file into the archive before the member specified by posname. If you do not 

specify posname, ar inserts file at the beginning of the archive. This option is the same as 

-b. 

puts any temporary files that ar generates in the current directory rather than the default 

temporary file directory. 

regenerates the symbol table regardless of whether the command modifies the archive. 

when used with -x, allows extraction of members with names longer than the file system 

supports; normally, this is an error, and ar does not extract the file. Most file systems 

truncate the file name to the appropriate length. 

350 of 457

-u 

-v 

replaces the member only if the modification time of the file member is more recent than the 

time of the archive member. -u implies -r, so it is not necessary to specify -r also. 

gives verbose output. With -d, -q, -r, and -x, this option displays the command letter and 

the member name affected before performing each operation. With -t, it prints more 

information about archive members using a format similar to ls -l. With -p, it displays the 

member name before the contents. 

DIAGNOSTICS 


0 

1 

2 



— inability to create the extracted file 

— an error writing to the extracted file 

— the requested module not found on appending 

— an error opening the module on appending 

— an invalid module on appending 

— inability to access the module on appending 

— a module not found on table/extraction 

Invalid command line arguments or options 

PORTABILITY 

POSIX.2. x/OPEN Portability Guide 4.0. Windows Me. Windows NT 4.0. Windows 2000. Windows 

XP. Windows Server 2003. All UNIX systems. 

On Windows systems, the archive format is either OMF, or the Common Object File Format 

(COFF). The options included in this implementation are the best possible approximation of those 

defined by the POSIX standard for the ar command, to make makefiles reasonably portable. For 

historical compatibility, you can omit the - preceding the options if the options appear only as the 

first argument after the command name. 

351 of 457

The following options are XPG extensions to the POSIX standard: -a, -b, -C, -i, -l, -m, -q, -s, 

and -T. 

The -F and -I options are extensions to the POSIX and XPG standards. 

AVAILABILITY 










SEE ALSO 

Commands: 

cc, make 

352 of 457

• 

NAME 

cc, cxx 

cc, cxx — interfaces to Microsoft C and C++ compilers 

SYNOPSIS 

cc [-c] [-C] [-Dname[=value]] [-e epsym] [-E] [-f[float]] [-g] [-Idirectory] [-llibrary] [-Ldirectory] 

[-m] [-mmodel] [-M] [-o output] [-O] [-P] [-s] [-S] [-static] [-U symname] [-VS num] [-Woption] 

[-x] [-Xc] files... 

cxx [-c] [-C] [-Dname[=value]] [-e epsym] [-E] [-g] [-Idirectory] [-llibrary] [-Ldirectory] [-m] [-M] 

[-o output] [-O] [-P] [-s] [-S] [-static] [-U symname] [-VS num] [-Woption] [-x] [-Xc] files... 

DESCRIPTION 

The cc and cxx commands serve as interfaces to the Microsoft C compiler (cl). Versions 5.0 and 

higher of this compiler are supported. cc is for compiling C files, while cxx is for compiling C++ 

files. 

Note: 

The behavior of cc depends upon whether or not you are working in the standard MKS 

Toolkit development environment or the development environment designed for use with the 

MKS Toolkit UNIX APIs. 

cxx is only available in the MKS Toolkit UNIX APIs development environment. 

These commands are just wrappers that invoke the cl utility. If you are using MKS Toolkit 

for Professional Developers or MKS Toolkit for Developers, the presence of cl in PATH is 

checked for during installation. For other Toolkit products, you must ensure yourself that cl 

is in the PATH. 

Files with a .c suffix are taken to be C source files, files with a .cpp or .cxx extension are taken 

to be C++ source files, and files with a .asm extension are taken to be assembly language source 

files. The presence of source files with a .cpp or .cxx automatically causes the source files to be 

compiled as if the cxx command had been invoked instead. 

The cc and cxx commands implicitly set the following Microsoft compiler switches (for Intel 

platforms only): 

353 of 457

Note: 

/D_X86_ 

/D_NUTC_=0x430 (Value changes with each release) 

/Zl 

/Qifdiv- 

The /D_NUTC_=0x430 option is only set when working in the MKS Toolkit UNIX APIs 

development environment. 

The /Qifdiv- option is only set when working in the MKS Toolkit UNIX APIs development 

environment and is only available for Microsoft Visual Studio 2.1 or later. 

You can use the -W/option flag to pass options directly to cl. In doing this, be careful not to 

conflict with the options that this command sets. For example, the default compiler warning level is 

set to /W3. The option -W/Wn can be used to override this default. cl options specified with -W 

override cl options generated by other cc or cxx options. 

Options 

-c 

-C 

compiles only — does not link. 

This option becomes the /c option to cl. 

passes comments through to preprocessor output. 

This option becomes the /C option to cl. 

-Dname[=value] 

defines a preprocessor symbol with an optional value. 

-E 

This option becomes the /Dname=value option to cl. 

sends all preprocessor output to standard output. 

This option becomes the /E option to cl. 

-e epsym 

sets entry point (passed through to linker). 

354 of 457

-ffloat 

specifies the floating point options that the compiler and linker use: 

Note: 

-g 

-f- no floating point required 

-f emulated floating point 

-fp hardware floating point (using 80x87 coprocessor) 

This option is obsolete and produces a warning. It is provided for backward compatibility and 

is not available with cxx or when working in the MKS Toolkit UNIX APIs development 

environment. 

produces debugging information in the compiled object modules. 

This option becomes the /Z7 option to cl. 

-I directory 

adds directory to the beginning of the list of directories to be searched for include files (the 

value of the %Include% environment variable). Any directories supplied on the command 

line are searched first, in the order in which they appear on the command line. 

This option becomes the /Idirectory option to cl. 

-l library 

if linking, adds the specified library to the list of libraries to be searched. In searching for 

libraries (for example, with -lfoo), each library directory is first searched for the UNIX-style 

archive name (that is, libfoo.a) and then for the Windows-style library name (that is, 

foo.lib). 

This option is passed through to the linker. 

-L directory 

if linking, adds the directory to the beginning of the list of directories that the linker searches 

for libraries (the value of the %Lib% environment variable). Any directories supplied on the 

command line are searched first, in the order in which they appear on the command line. 

-m 


produces a link map. 

355 of 457


-mmodel 

specifies the memory model that the compiler and linker use. The models may include: 

Note: 

-M 

-ms small model 

-mm medium model 

-ml large model 

-mf flat model (32-bit) 

-mc compact model 

-mh huge model 

This option is obsolete and produces a warning. It is provided for backward compatibility and 

is not available with cxx or when working in the MKS Toolkit UNIX APIs development 

environment. 

complains about multiply defined symbols. 

Note: 

This behavior is only available when working in the MKS Toolkit UNIX APIs 

development environment. Otherwise, -M is identical to the -m option. 

-o output 

specifies the name of the output file generated by the linker. This option is passed to the 

linker. If -c and -o are both specified, the -o option is ignored; however, you can specify a 

name for the oject file generated with -W/Foobj_file. 

-O 

Note: 

When working in the MKS Toolkit UNIX APIs development evironment, the -o option 

is not ignored. Instead, it behaves like -W/Foobj_file and specifies the name of the 

object file generated. 

File names specified with the -W/Fo option should have a .o or .obj extension. If the file 

name does not have such an extension, its current extension is replaced with .obj before 

invoking the linker. However, when -c is also specified, there are no restrictions on the 

extension of the specified file. 

instructs the compiler to generate optimized code. 

This option becomes the /Ox option to cl. 

356 of 457

-P 

-s 

-S 

stores preprocessor output to a file, where the file name is obtained by replacing the .c (or 

.cpp) extension with .i. 

when linking, strips debugging information from the output file. 


produces an assembly code listing. The suffix for the listing file is .asm. This listing includes 

source and assembly code. 

This option becomes the /FAs option to cl. 

-static 

requests linking against the static C++ runtime libraries. This is not recommended. 

When this option is not specified, the /MD to cl is the defaul for C++ and multithreaded 

DLLs are produced. 

-u symname 

when linking, adds an undefined reference to symname. 


-U symname 

undefines the specified preprocessor symbol. 

This option becomes the /Usymname option to cl. 

-VS num 

passes through to the /VERSION linker option. 

-Wc++ 

forces C++ linking. 


Note: 

The C++ library paths are only available when working in the development 

357 of 457

-Wv 

environment for the MKS Toolkit UNIX APIs. If you are not working in this 

environment, you must specify these library paths with the -L option. 

selects verbose mode. 


-W/option 

specifies an option that is to be passed either to the C compiler or to linker with the leading 

-W removed. The options — subsystem, def, base, entry, implib, machine, map, out, 

stack, and dll — are passed to the linker; all others are passed to the compiler. 

-x 

-Xc 

-Xa 

-Xs 

-Xt 

when linking, strips debugging information related to local symbols from the output file. 


compiles with strict ANSI C conformance. Only symbols specified by the ANSI C 

specification are visible during compilation. 

This option becomes the /D__STRICT_ANSI=1 and /D__STDC__=1 options to cl. 

compiles with non-strict ANSI C conformance. Only symbols specified by the ANSI C 

specification are visible during compilation. 

This option becomes the /D__STDC__=0 to cl. 

While this reference page describes cc as an interface to the Microsoft C compiler, that is not the 

complete truth. In truth, cc is a configurable interface to any C compiler and is designed for use 

with make. Theoretically, you can simply redefine cc on each system to work with that system's C 

compiler and by simply using cc in your makefiles, you can use those same makefile across 

different system. 

cc uses a compilation configuration file to convert arguments on a standard command line into 

the arguments for the command or sequence of commands needed to call your compiler or linker. 

If you want to change your compiler or linker, change the appropriate configuration file; do not 

change your makefile. 

358 of 457

The default configuration file for cc is 

ROOTDIR/etc/compiler.ccg 

You may chose a different configuration file by setting the environment variable CCG to point to the 

desired file. Interfaces to other compilers may be available from MKS. 

If you want cc to temporarily use a different compiler, you can set the environment variable CCG to 

the name of the configuration file for the desired compiler. 

If you rename the cc executable, it attempts to find its default configuration in a .ccg file with the 

same base name as the renamed executable. For example, if you rename cc.exe to c89.exe, 

c89 looks for a default configuration file named c89.ccg in ROOTDIR/etc. 

If you use a compiler that does not have a configuration file, you can customize a given 

configuration file to use your compiler. Read the cc miscellaneous information reference page 

carefully, and modify an existing configuration to use your compiler. 


CCG 

identifies the configuration file for the desired compiler. If CCG contains -, cc reads the 

default configuration from the standard input. If CCG contains a file name, cc uses that file 

as its default configuration file. If CCG contains a directory name, cc looks for the default 

configuration in the cc.ccg file in that directory. If the executable has been renamed, it 

looks for the default configuration in a .ccg file with the same name as the executable. For 

example, if cc.exe is renamed to c89.exe, it looks for the default configuration in 

$CCG/c89.ccg. 

DIAGNOSTICS 


0 

>0 


An error occurred. 

AVAILABILITY 

359 of 457

The cc command is available with the following products: 









The cxx command is available with the following products: 





SEE ALSO 

Commands: 

ld, make 


cc 

360 of 457

NAME 

cmp — compare two files 

SYNOPSIS 

cmp [-blsx] file1 file2 [seek1[seek2]] 

DESCRIPTION 

cmp 

cmp compares two files. If either file name is -, cmp reads the standard input for that file. By 

default, cmp begins the comparison with the first byte of each file. If you specify seek1 and/or 

seek2, cmp uses it as a byte offset into file1 or file2 (respectively), and comparison begins at that 

offset instead of at the beginning of the files. The comparison continues (one byte at a time) until a 

difference is found, at which point the comparison ends and cmp displays the byte and line number 

where the difference occurred. cmp numbers bytes and lines beginning with 1. 

Options 

-b 

-l 

-s 

-x 

EXAMPLE 

compares single blocks at a time. Normally, cmp reads large buffers of data into memory for 

comparison. 

causes the comparison and display to continue to the end. cmp displays the byte number (in 

decimal) and the differing bytes (in octal) for each difference found. cmp attempts no 

resynchronization. 

suppresses output and returns a non-zero status if the files differ. 

displays the differing bytes shown by the -l option in hex. 

To determine if prog.exe and prog.com are instances of the same program (generated, for 

example, by exe2bin) 

361 of 457

cmp prog.exe prog.com 512 

DIAGNOSTICS 


0 

1 

2 

3 

Messages 

The files were identical. 

The files were not identical. 

Failure due to invalid command line argument or option. 

Failure because of an error opening or reading an input file. 

EOF on filename 

cmp reached end-of-file on the specified file before reaching end-of-file on the other file. 

PORTABILITY 


Windows 2000. Windows XP. Windows Server 2003. The -b and -x options and the seek pointers 

are extensions to the POSIX standard. 

AVAILABILITY 











362 of 457

SEE ALSO 

Commands: 

comm, diff, uniq 

363 of 457

NAME 

cp — copy files 

SYNOPSIS 

cp [-acfimPpSv] file1 file2 

cp [-acfimPpSv] file ... directory 

cp -R [-acfimPpSv] source... directory 

cp -r [-acfimPpSv] source... directory 

DESCRIPTION 

cp 

cp copies files to a target named by the last argument on its command line. If the target is an 

existing file, cp overwrites it; if it does not exist, cp creates it. If the target file already exists and 

does not have write permission, cp denies access and continues with the next copy. 

If you specify more than two path names, the last path name (that is, the target) must be a 

directory. If the target is a directory, cp copies the sources into that directory with names given by 

the final component of the source path name. 

Normally, the destination file has its file mode (see chmod) set to 777 (that is, readable, writable, 

and executable by everyone) and sets the file modification time to the present. The -m and -p 

options can override this behavior. 

If a file being copied is a sparse file and the file system to which it is being copied does not support 

sparse files, cp warns that the resulting file will be larger. If the -i option was also specified, cp 

asks you if want to expand the file or skip it. The -S option overrides this behavior and expands all 

sparse files automatically when copying. 

Options 

-a 

-c 

copies the DACLs associated with the specified file along with the file itself. 

This option is only available on NTFS file systems. 

364 of 457

-f 

-i 

-m 

-P 

-p 

-R 

-r 

-S 

-v 

prompts you to change the diskette if there is insufficient room to complete a copy operation. 

The parent directories must already exist on the new target diskette. This option has no 

effect on systems without floppy drives. 

attempts to replace files that do not have write permission. 

asks you if you want to overwrite an existing file, whether or not the file is read-only. 

sets the modification time, access time, and file mode (see chmod) of each destination file to 

those of the corresponding source file. The compression and archive bits of the file mode 

are handled separately. The compression bit for each destination file is always unset, while 

the archive bit is always set. 

prevents the -m and -p options from copying the file mode (see chmod). This option always 

sets the archive bit on the copied file. 

The behavior of this option is identical to setting the TK_CP_NOPRESERVE environment 

variable. 

is similar to the -m option, but also sets the owner and group of each destination file to the 

owner and group of the corresponding source file. Unlike the -m option, the archive bit of all 

destination files is always unset. 

reproduces the source trees. cp copies all files and subdirectories specified by source.... 

into directory, making careful arrangements to duplicate special files (FIFO, block special, 

character special). 

reproduces the source trees, but makes no allowances for special files (FIFO, block special, 

character special). Consequently, cp attempts to read from a device rather than duplicate 

the special file. This is similar to, but less useful than, the preferred -R. 

automatically expands sparse files. This lets you make a non-sparse copy of a sparse file. 

prints file names to standard output as they are being processed. 

365 of 457


TK_CP_NOPRESERVE 

when set, this variable prevents the -m and -p options from copying the file mode (see 

chmod). This option always sets the archive bit on the copied file. 

DIAGNOSTICS 


0 

1 

2 



— an argument had a trailing slash (/) but was not a directory 

— unable to find a file 

— unable to open an input file for reading 

— unable to create or open an output file 

— a read error occurred on an input file 

— a write error occurred on an output file 

— the input and output files were the same file 

— encountered a fatal error when using -r or -R 

Possible fatal -r or -R errors include: 

— inability to access a file 

— inability to change permissions on a target file 

— inability to read a directory 

— inability to create a directory 

— a target that is not a directory 

— source and destination directories are the same 


— an invalid command line option 

— too few arguments on the command line 

— a target that should be a directory but is not 

— no space left on target device 

— out of memory to hold the data to be copied 

— inability to create a directory to hold a target file 

366 of 457

cannot allocate target string 

cp has no space to hold the name of the target file. Try to free up some memory to give cp 

more space. 

"name" is a directory (not copied) 

You did not specify -r or -R, but one of the names you asked to copy was the name of a 

directory. 

"target name"? 

You are attempting to copy a file with the -i option, but there is already a file with the target 

name. If you have specified -f, you can write over the existing file by typing y and pressing 

ENTER; if you do not want to write over the existing file, type n and press ENTER. If you did 

not specify -f and the file is read only, you are not given the opportunity to overwrite it. 

source "name" and target "name" are identical 

The source and the target are actually the same file (for example because of links, on UNIX 

and POSIX-compliant systems). In this case, cp does nothing. 

unreadable directory "name" 

cp cannot read the specified directory, for example, because you do not have appropriate 

permissions. 

PORTABILITY 



The -c, -f, -m, and -v options are extensions to the POSIX standard. On Windows systems, the 

-R and -r options are equivalent since special files (FIFO, block special, character special) are not 

supported on Windows file systems. 

AVAILABILITY 










367 of 457


SEE ALSO 

Commands: 

cat, chmod, ln, mv, rm 

368 of 457

NAME 

date — set and display date and time 

SYNOPSIS 

date [-ctu] [timespec] 

date [-cu] [+format] 

DESCRIPTION 

date -- Command, KornShell Built-in 

date either displays the operating system's idea of the current date and time or sets it to a new 

value. The following example shows the default format of the date: 

Options 

-c 

-t 

-u 

Wed Feb 26 14:01:43 EST 1998 

sets or displays the date and time according to Greenwich Mean Time (Coordinated 

Universal Time) using CUT as the time zone name. 

specifies that the BSD format is used when setting the date and time. 

sets or displays the date and time according to Greenwich Mean Time (Coordinated 

Universal Time) using GMT as the time zone name. 

Setting Date and Time 

date also accepts an argument in one of two forms. If the argument does not begin with +, date 

assumes it is a timespec to set the date and time. The timespec can have the form 

or 

[[mm]dd]hhmm[.ss] 

mmddhhmmyy[.ss] 

369 of 457

where mm is the optional number of the month (01-12), dd is the optional day of the month, hh is 

the hour in 24 hour format (required) mm is the minutes (required), yy is the optional last 2 digits of 

the year, and ss is the optional seconds. 

date uses these values to set the date and time. 

Note: 

You must specify the hours and the minutes; other arguments are optional. The year can be 

specified only if you have specified the month and day. 

The -t option allows you to use the BSD date format, which is: 

[[[[cc]yy]mm]dd]hhmm[.ss] 

where cc is the optional first 2 digits of the year. 

Displaying Date and Time 

If the argument to date begins with a + character, date uses format to display the date. date 

writes all characters in format, with the exception of the % and the character which immediately 

follows it, directly to the standard output. After date exhausts the format string, it outputs a newline 

character. The % character introduces a special format field similar to the printf() function in the 

C library (see Field Descriptors). 

Field Descriptors 

%A 

%a 

%B 

%b 

%C 

%c 

%D 

the full weekday name in the current locale (for example, Sunday, in the POSIX locale). 

the abbreviation for the weekday in the current locale (for example, Sun, in the POSIX 

locale). 

the full month name in the current locale (for example, February, in the POSIX locale). 

the abbreviation for the month name in the current locale (for example, Feb, in the POSIX 

locale). 

the first two digits of the year (19 or 20). 

the appropriate representation of the date and time in the current locale. 

the date in the form mm/dd/yy. 

370 of 457

%d 

%e 

%H 

%h 

%I 

%j 

%M 

%m 

%n 

%p 

%R 

%r 

%S 

%T 

%t 

%U 

%u 

%V 

%W 

%w 

the two-digit day of the month as a number (01 to 31). 

the day of the month in a two-digit, right-justified, blank-filled field ( 1 to 31). 

the hour in the 24-hour clock representation (00 to 23). 

the same as %b. 

the hour in the 12-hour clock representation (01 to 12). 

the numeric day of the year (001 to 366). 

the minute (00 to 59). 

the month number (01 to 12). 

a newline character. 

the equivalent of AM or PM in the current locale. 

the 24-hour time (for example, 14:53). 

the 12-hour time in the current locale's equivalent of AM/PM notation (for example, 11:53:29 

AM in the POSIX locale). 

the seconds (00 to 61). Note that there is an allowance for two leap seconds. 

the 24-hour time (for example, 14:53:29). 

a tab character. 

the week number in the year, with Sunday being the first day of the week (00 to 53). All days 

before the first Sunday of the new year are in week 0. 

the weekday number with Monday being 1 and Sunday being 7. 

the week number in the year, with Monday being the first day of the week (01 to 53). If the 

week containing January 1 has four or more days in the new year, it is week 1 of the new 

year; otherwise it is week 53 of the previous year. 

the week number in the year, with Monday being the first day of the week (00 to 53). All 

days before the first Monday of the new year are in week 0. 

the weekday number, with Sunday being 0 and Saturday being 6. 

371 of 457

%X 

%x 

%Y 

%y 

%Z 

%z 

%% 

the appropriate time representation in the current locale. 

the appropriate date representation in the current locale. 

the four-digit number of the year (for example, 1998). 

the two-digit year (offset from %C). 

the time zone name (for example, EDT). 

equivalent to %Z. 

a percent-sign character. 

The date command also supports the following modified field descriptors to indicate a different 

format as specified by the locale indicated by LC_TIME. If the current locale does not support a 

modified descriptor, date uses the unmodified field descriptor value. 

%EC 

%Ec 

%EX 

%Ex 

%EY 

%Ey 

%Od 

%Oe 

%OH 

%OI 

%OM 

%Om 

the name of the base year (period) in the current locale's alternate representation. 

the current locale's alternate date and time representation. 

the current locale's alternate time representation. 

the current locale's alternate date representation. 

the full alternate year representation. 

the offset from %EC (year only) in the current locale's alternate representation. 

the day of month using the current locale's alternate numeric symbols. 

the day of month using the current locale's alternate numeric symbols in a two-character, 

right-justified, blank-filled field. 

the hour (24-hour clock) using the current locale's alternate numeric symbols. 

the hour (12-hour clock) using the current locale's alternate numeric symbols. 

the minutes using the current locale's alternate numeric symbols. 

the month using the current locale's alternate numeric symbols. 

372 of 457

%OS 

%OU 

%Ou 

%OV 

%OW 

%Ow 

%Oy 

the seconds using the current locale's alternate numeric symbols. 

the week number of the year (with Sunday as the first day of the week) using the current 

locale's alternate numeric symbols. 

the weekday number using the current locale's alternate numeric symbols with Monday 

being 1 and Sunday being 7. 

the week number in the year using the current locale's alternate numeric symbols, with 

Monday being the first day of the week. If the week containing January 1 has four or more 

days in the new year, it is week 1 of the new year; otherwise it is week 53 of the previous 

year. 

the week number of the year (with Monday as the first day of the week) using the current 

locale's alternate numeric symbols. 

the weekday as a number using the current locale's alternate numeric symbols with Sunday 

being 0 and Saturday being 6. 

the year (offset from %C) using the current locale's alternate numeric symbols. 

EXAMPLES 

The command 

date '+%a %b %e %T %Z %Y' 

produces the date in the default format. For example, 

Wed Feb 26 14:01:43 EST 1998 


TZ 

gives the time zone for date to use when displaying the times. This is ignored if you specify 

either the -c or the -u option. For more information on this variable, see timezone. 

DIAGNOSTICS 


373 of 457

0 

1 

2 



— a bad date conversion 

— a formatted date that was too long 

— you do not have permission to set the date 

Usage error, including: 

— an invalid command line option 

— too many arguments on the command line 

Possible error messages include: 

Bad date conversion: "string" 

The date and/or time specified on the command line had an invalid format (for example, if 

the hour is greater than 24). 

Bad format character x 

A character following % in the format string was not in the list of field descriptors. 

No permission to set date 

The system has denied you the right to set the date. 

PORTABILITY 



The -c option, the -t option, and the %z format specifier are extensions to both the POSIX and 

x/OPEN standards. The %R format specifier is an x/OPEN extension to the POSIX standard. 

On Windows NT/2000/XP/2003, you can specify the current locale using the Regional Settings 

item of the Control Panel. 

NOTES 

date is provided as both an external utility and a built-in MKS KornShell utility. 

374 of 457

On machines that have a time-of-day clock with battery backup, using date does not necessarily 

change this real-time clock. There is probably an operating system-specific command to achieve 

this. 

The date command supplied with MKS Toolkit should not be confused with the date command 

internal to the native command interpreters on Windows systems (that is, command.com and 

cmd.exe). 

AVAILABILITY 











SEE ALSO 

Commands: 

sh, touch 


timezone 

375 of 457

NAME 

diff, diffh, bdiff, vdiff32 

diff, diffh, bdiff, vdiff32 — compare two text files and show differences 

SYNOPSIS 

diff [-BbefHhimnrsw] [-C n] [-c[n]] [-Difname] [-Mmark] [-U[b|B|l|L]] path1 path2 

diff [-BbefHhimnrsw] [-C n] [-c[n]] [-Difname] [-Mmark] [-U[b|B|l|L]] file... dir 

diffh [-Bbefimnrsw] [-C n] [-c[n]] [-Difname] [-Mmark] [-U[b|B|l|L]] path1 path2 

diffh [-Bbefimnrsw] [-C n] [-c[n]] [-Difname] [-Mmark] [-U[b|B|l|L]] file... dir 

bdiff [-Bbefimnrsw] [-C n] [-c[n]] [-Difname] [-Mmark] [-U[b|B|l|L]] path1 path2 [n] 

bdiff [-Bbefimnrsw] [-C n] [-c[n]] [-Difname] [-Mmark] [-U[b|B|l|L]] file... dir [n] 

vdiff32 

DESCRIPTION 

The diff command attempts to determine the minimal set of changes needed either to convert a 

file named path1 into path2 or the group of files indicated by file... into files of the same name 

found under the directory dir. Besides normal text files, diff also works on 16-bit Unicode files. 

Such files normally begin with a two-byte marker indicating whether the file's Unicode characters 

are big-endian or little-endian. 

If either (but only one) file name is -, diff reads that file from the standard input. If only two path 

names appear on the command line and one of path1 or path2 is a directory, diff uses a file in 

that directory with the same name as the other file name. If both are directories, diff compares 

files with the same file names under the two directories. However, diff does not compare files in 

subdirectories unless you specify the -r option. When comparing two directories, diff does not 

compare block special files, character special files, or FIFO special files to any other files and does 

not compare regular files to directories. 

If more than two path names appear on the command line, the last path name is assumed to be a 

directory and the preceding path names to be files. diff then compares each file in the list to a file 

with the name under the specified directory. 

By default, output consists of descriptions of the changes in a style reminiscent of the ed text 

editor. A line indicating the type of change is given. The three types are a (append), d (delete), and 

c (change). The output is symmetric in the sense that a delete in path1 is the counterpart of an 

append in path2. diff prefixes each operation with a line number (or range) in path1 and suffixes 

376 of 457

each with a line number (or range) in path2. After the line giving the type of change, diff displays 

the deleted or added lines, prefixing lines from path1 with < and lines from path2 with >. 

When you call the command as diffh, it automatically uses the -h option. 

When you call it as bdiff, diff computes the differences in chunks of n lines (default 3999). This 

lets you process arbitrarily large files and generally produces less output than the -h option. 

The vdiff32 command is a graphical version of diff, giving you the ability to compare and view 

files from a graphical user interface. Complete instructions on using vdiff32 are available 

through its online help feature. 

Options 

-B 

-b 

-C n 

-c[n] 

uses diffb to compare the files when binary files are detected. 

ignores white space at the end of each line (except the newline) and treats all consecutive 

strings of white space elsewhere in a line as equivalent (effectively, reducing all strings of 

white space to a single space for the purpose of comparing lines). For example if one file 

contained a string of three spaces and a tab at a given location while the other file contained 

a string of two spaces at the same location, diff would not report this as a difference. 

shows n lines of context before and after each change. diff marks lines removed from 

path1 with -, lines added to path2 with + and lines changed in both files with !. This option 

conflicts with the -e and -f options. 

is equivalent to -C n, but n is optional. The default value for n is 3. This option conflicts with 

the -e and -f options. 

-Difname 

displays output that is the appropriate input to the C preprocessor to generate the contents 

of path2 when ifname is defined, and the contents of path1 when ifname is not defined. 

-e 

-f 

writes out a script of commands for the ed text editor that converts path1 to path2. diff 

sends the output to the standard output. This option conflicts with the -m, -c, and -C 

options. 

377 of 457

-H 

-h 

-i 

writes a script similar to the one produced under -e to the standard output, but with the 

command sequence reversed, the command form reversed, and the line-range separator a 

space, rather than a comma. This option conflicts with the -m, -c, and -C options. 

uses the half-hearted (-h) algorithm only if the normal algorithm runs out of system 

resources. 

uses a fast, half-hearted algorithm instead of the normal diff algorithm. This algorithm can 

handle arbitrarily large files; however, it is not particularly good at finding a minimal set of 

differences in files with many differences. 

ignores the case of letters when doing the comparison. 

-Mmark 

describes the diff mark to be used in place of the vertical line character (|) when the -m 

option is also specified. mark can be any nroff/troff character or string. It can be as 

simple or complex as you like. For example, specifying mark as 1 causes the diff mark to be 

the character 1. Specifying \(sq causes it to be an open square and specifying 

\s+6\fB\d~\u\fP\s0 causes the diff mark to be a bold-faced tilde (~) six points larger in 

size half a line below the current line. 

-m 

-n 

-r 

This option does not change the character used to indicate deleted lines. It remains the 

asterisk(*). 

produces the contents of path2 with extra formatter request lines interspersed to show which 

lines were added or changed and which were deleted. 

If you do not also specify the -M option, added, or changed lines are indicated by a vertical 

line character | in the right margin. If you do specify the -M option, diff uses the 

nroff/troff string given as mark to indicated additions or changes. Deleted lines are 

always indicated with an asterisk (*) in the right margin. 

These are nroff/ troff requests. This option conflicts with the -e and -f options. 

displays the differences in a form that is usable by MKS Source Integrity. 

compares corresponding files under the directories, and recursively compares 

378 of 457

-s 

corresponding files under corresponding subdirectories. You can use this option when you 

specify two directory names on the command line. 

compares two directories, file by file, and prints messages for identical files between the two 

directories. 

-U[b|B|l|L] 

forces the specified files to be treated as Unicode files. 

-w 

By default, diff assumes that Unicode characters are little-endian. If a byte-order marker is 

present, that is used to determine the byte order for the characters. You can force Unicode 

characters to be treated as big-endian by specifying -Ub or -UB. Similarly, you can force 

them to be treated as little-endian by specifying -Ul or -UL. 

ignores white space (not including newlines) when making the comparison. For example, 

the following two lines are equivalent: 

a b c d 

abcd 

EXAMPLES 

The following example illustrates the output of the diff command. The following two files, price1 

and price2, are compared with and without the use of the -c option. 

The contents of price1 are as follows: 

Company X Price List: 

$ 0.39 -- Package of Groat Clusters 

$ 5.00 -- Candy Apple Sampler Pack 

$ 12.00 -- Box of Crunchy Frog Chocolates 

$ 15.99 -- Instant Rain (Just Add Water) 

$ 20.00 -- Asparagus Firmness Meter 

$ 25.00 -- Package of Seeds for 35 Herbs 

$ 30.00 -- Child's Riding Hood (Red) 

$ 35.00 -- Genuine Placebos 

$ 45.00 -- Case of Simulated Soy Bean Oil 

$ 75.88 -- No-Name Contact Lenses 

$ 99.99 -- Kiddie Destructo-Bot 

$125.00 -- Emperor's New Clothes 

379 of 457

The contents of price2 are as follows: 



$ 5.49 -- Candy Apple Sampler Pack 



$ 17.00 -- Simulated Naugahyde Cleaner 




$ 35.00 -- Genuine Placebos 




The command 

diff price1 price2 

results in the following output: 

4c4 

< $ 5.00 -- Candy Apple Sampler Pack 

--- 

> $ 5.49 -- Candy Apple Sampler Pack 

6a7 

> $ 17.00 -- Simulated Naugahyde Cleaner 

14d14 

< $125.00 -- Emperor's New Clothes 

The addition of the -c option, as in 

diff -c price1 price2 

results in the following output: 

*** price1 Wed Mar 04 10:08:40 1992 

--- price2 Wed Mar 04 10:09:10 1992 

*************** 

*** 1,9 **** 



380 of 457

! $ 5.00 -- Candy Apple Sampler Pack 






--- 1,10 ---- 



! $ 5.49 -- Candy Apple Sampler Pack 



+ $ 17.00 -- Simulated Naugahyde cleaner 




*************** 

*** 11,14 **** 




- $125.00 -- Emperor's New Clothes 

--- 12,14 ---- 

diff -c marks lines removed from price1 with -, lines added to price1 with + and lines 

changed in both files with !. In the example, diff shows the default 3 lines of context around 

each changed line. One line was changed in both files (marked with !), one line was added to 

price1 (marked with +), and one line was removed from price1 (marked with -). 

Note: 

If there are no marks to be shown in the corresponding lines of the file being compared, the 

lines are not displayed. Lines 12 to 14 of price2 are suppressed for this reason. 

DIAGNOSTICS 


0 

1 

No differences between the files compared. 

diff compared the files and found them to be different. 

381 of 457

2 

4 

Messages 


— invalid command line argument 

— cannot open one of the input files 

— out of memory 

— read error on one of the input files 

— more than LINE_MAX characters between newlines 

At least one of the files is a binary file containing embedded NUL (\0) bytes. 

file "filename": no such file or directory 

The specified filename does not exist. filename was either typed explicitly, or generated by 

diff from the directory of one file argument and the base name of the other. 

Files file1 and file2 are identical 

The -s option was specified and the two named files are identical. 

Common subdirectories: name and name 

This message appears when diff is comparing the contents of directories, but you have 

not specified -r. When diff discovers two subdirectories with the same name, it reports 

that the directories exist, but it does not try to compare the contents of the two directories. 

Insufficient memory (try diff -h) 

diff ran out of memory for generating the data structures used in the file differencing 

algorithm (see LIMITS). The -h option of diff can handle any size of file without running 

out of memory. 

Internal error--cannot create temporary file 

diff was unable to create a working file that it needed. Ensure that you either have a /tmp 

directory or that the environment contains a variable TMPDIR that names a directory where 

diff may store temporary files. Also, ensure that there is sufficient file space in this 

directory. 

Missing #ifdef symbol after -D 

You did not specify a conditional label on the command line after the -D option. 

Only one file may be "-" 

Of the two input files normally found on the command line of diff, only one can be the 

standard input. 

382 of 457

Too many lines in "filename" 

A file of more than the maximum number of lines (see LIMITS) was given to diff. 

LIMITS 

The longest input line is 8192 on Windows and most UNIX systems. -h, files are limited to 

INT_MAX lines. 

PORTABILITY 



The -D, -H, -h, -i, -m, -n, -s, and -w options; the n argument to the -c option; and the diffh 

and bdiff versions of the command are extensions to the POSIX and x/OPEN standard. The -f 

option is an x/OPEN extension to the POSIX standard. 

AVAILABILITY 

The diff, bdiff, and diffh utilities are available with the following products: 











The vdiff32 utility is only available with the following products: 








383 of 457

SEE ALSO 

Commands: 

cmp, comm, diff3, diffb, dircmp, patch 

384 of 457

NAME 

diffb 

diffb — compare binary files and show differences 

SYNOPSIS 

diffb [-n] [-C n] [-c[n]] file1 file2 

DESCRIPTION 

The diffb utility indicates which bytes differ in the binary files file1 and file2. Output consists of 

descriptions of the changes in a style reminiscent of the ed text editor. Each description is headed 

by a line showing the type of change being performed. This line contains three pieces of 

information: 

● the location of the range of bytes in file1 affected by the change, represented as an offset 

from the beginning of the file; 

● the type of change: one of a (append), d (delete), and c (change); 

● the location of the range of bytes in file2 affected by the change. 

After the line giving the type of change, the deleted or added bytes are displayed. Non-printable 

bytes are represented by an escape sequence consisting of a backslash character (\), followed by 

the ASCII representation of the byte displayed as a three-digit octal number. 

The output of diffb resembles the output of diff, except that differences are ranges of bytes 

rather than ranges of lines. Each displayed set of bytes from file1 is prefixed by , and a > appears at the start of each new line in a set of 

bytes. If bytes from both file1 and file2 are being displayed, a line consisting of --- separates the 

two sets of bytes. 

Options 

-C n 

-c[n] 

-n 

is equivalent to -c n. 

displays n bytes of context before and after each difference. The default value for n is 3. 

displays the differences in a form usable by MKS Source Integrity. 

385 of 457

DIAGNOSTICS 


0 

1 

2 

LIMITS 

The files were identical. 

The files were compared successfully and found to be different. 


— the inability to open an input file 

— a syntax error on the command line 

— the wrong number of arguments on the command line 

The set of differences produced by diffb is correct but may not be minimal. 

PORTABILITY 

Windows Me. Windows NT 4.0. Windows 2000. Windows XP. Windows Server 2003. 

AVAILABILITY 











SEE ALSO 

Commands: 

386 of 457

diff 

387 of 457

NAME 

echo — display arguments 

SYNOPSIS 

echo argument... 

DESCRIPTION 

echo -- Command, KornShell Built-in 

echo writes its arguments to the standard output. echo accepts these C-style escape sequences: 

\a 

bell 

\b 

backspace 

\c 

removes any following characters including \n and \r 

\e 

escape character 

\E 

escape character 

\f 

formfeed 

\n 

newline 

\r 

carriage return 

\t 

horizontal tab 

\v 

vertical tab 

\xHH 

the character whose hexadecimal value is HH (on or two hex digits). 

\0num 

the byte with the numeric value specified by the zero to three digit octal num 

\\ 

backslash 

echo follows the final argument with a newline unless it finds \c in the arguments. Arguments are 

388 of 457

subject to standard argument manipulation. 

Because echo interprets backslashes as the beginning of an escape sequence and path names 

can contain backslashes, echo can produce unusual results when attempting to display the value 

of PATH or any string may contain path names. To display such strings properly, you should use 

print -r instead of echo. 

EXAMPLES 

One use of echo is to expand file names on the command line, as in: 

echo *.[ch] 

This displays the names of all files with names ending in .c or .h, typically C source and header 

files. echo displays the names on a single line. If there are no file names in the current directory 

that end in .c or .h, echo simply displays the string *.[ch]. 

echo is also handy for passing small amounts of input to other filters: 

echo 'this is\nreal handy' | banner 

DIAGNOSTICS 

echo always returns the status value: 

0 


PORTABILITY 

POSIX.2. x/OPEN Portability Guide 4.0. UNIX System V. Windows Me. Windows NT 4.0. Windows 

2000. Windows XP. Windows Server 2003. 

The POSIX.2 standard does not include the escape sequences, so a strictly conforming application 

cannot use them. printf is suggested as a replacement. 

On older UNIX systems, the backslash escape sequences are not available; the -n option is 

equivalent to \c embedded in an argument. 

NOTE 

389 of 457

echo is provided as both an external utility and a built-in MKS KornShell utility. The echo 

command provided with MKS Toolkit should not be confused with the echo command provided 

with Windows. 

To gain access to this command on Windows systems, outside the MKS KornShell, do one of the 

following: 

● call echo with its full path name (usually, $ROOTDIR/mksnt/echo.exe) 

● copy echo.exe to another file name to avoid a clash with the built-in command 

AVAILABILITY 











SEE ALSO 

Commands: 

print, sh 

390 of 457

ident 

look for keywords in a file 

SYNOPSIS 

ident [-q] [-Ffile]... [file ...] 

DESCRIPTION 

ident searches the named files (or the standard input if you do not specify any files) for all 

occurrences of the pattern $keyword:...$, where keyword is one of the following MKS Source 

Integrity keywords: 

$Author$ 

$Date$ 

$Header$ 

$Id$ 

$Locker$ 

$Log$ 

$Name$ 

$ProjectName$ 


$RCSfile$ 

$Revision$ 

$Source$ 

$State$ 

ident works on any file, but the file must have been checked out with keyword expansion turned 

on for the results to be meaningful. 

The ident command works on object files and dumps as well as text files. For example, if the C 

program in file f.c contains 

char rcsid[] = "$Header$"; 

and f.c is compiled into f.o, the command 

displays 

ident f.c f.o 

391 of 457

f.c: 

f.o: 

Options 

-Ffile 

-q 

$Header$ 

$Header$ 

provides an alternate way to specify file names. The given file is a text file containing a list of 

file names, one file name per line. ident checks all the files named in file, using the options 

specified on the command line. Multiple -F options may be specified on the command line, 

and can either be grouped together or interspersed between options. 

suppresses the warning given if there are no keywords in a file. 

DIAGNOSTICS 


0 

1 


Failure due to an invalid command line argument, or inability to open input file. 

392 of 457

NAME 

more 

more, less — display files on a page-by-page basis 

SYNOPSIS 

more [-ceiSs] [-A|-u] [-n number] [-P prompt] [-p command] [-t tag] [-U[b|B|l|L]] [file ...] 

more [-ceiSs] [-A|-u] [-n number] [-P prompt] [-t tag] [+command] [-U[b|B|l|L]] [file ...] 

less [-ceiSs] [-A|-u] [-n number] [-P prompt] [-p command] [-t tag] [-U[b|B|l|L]] [file ...] 

less [-ceiSs] [-A|-u] [-n number] [-P prompt] [-t tag] [+command] [-U[b|B|l|L]] [file ...] 

DESCRIPTION 

The more command displays files one page at a time. It obtains the number of lines per page from 

the environment or from the -n option. If the standard output is not a terminal device, the number 

of lines per page is infinite. The less command is identical to the more command. 

If more than one file is specified, they are displayed one at a time. When more finishes displaying 

one file, it begins displaying the next one in the list. If you give - as one of the file names, more 

reads the standard input at that point in the sequence. 

Besides normal text files, more also works on 16-bit Unicode files. Such files normally begin with a 

two-byte marker indicating whether the file's Unicode characters are big-endian or little-endian. 

more allows paging forwards and backwards (if possible) and searching for strings. 

Options 

-A 

-c 

causes the display of all characters, including unprintable ones. Normally unprintable 

characters are displayed in a printable format. Further, ANSI escape sequences for display 

modes are processed. This option cannot be used with -u. 

Note: 

The character in the top left corner of the screen always appears in normal mode. 

clears the screen before displaying a new file. If at any time, the new screen to be displayed 

393 of 457

-e 

-i 

does not have any lines in common with the current screen, more does not scroll, but 

instead, redraws the screen one line at a time, starting from the top. more may ignore this 

option if the terminal does not support such operations. 

exits immediately after displaying the last line of the last file. Normally, if standard output is a 

terminal device, more stops after displaying the last line of the last file and prompts for a 

new command. If the command that displays text causes more to reach the end of the file 

again, more exits. 

ignores case during searches. 

-n number 

specifies the number of lines per page. This overrides any values obtained from the 

environment. 

-P string 

sets the prompt that appears at end of each page of text to string. The default prompt is 

[filename]. more normally displays the prompt in STANDOUT mode. 

-p command 

+command 

initially executes the more command on each file. If it executes successfully and command 

is a positioning command such as a line number or a regular expression search, more 

displays the resulting page; otherwise more displays the first page of the file. If both the -t 

and -p options are specified, the -t option is processed first. 

-S 

-s 

displays the prompt in normal mode rather than STANDOUT mode. 

replaces consecutive empty lines with a single empty line. Remember that all line numbers 

(for example, as specified with the p) will refer to the lines in the new file (that is, the file with 

the consecutive empty lines replaced). 

-t tag 

searches for the named tag and displays the page of text containing it. See ctags for more 

information. 

-U[b|B|l|L] 

forces the specified files to be treated as Unicode files. 

394 of 457

-u 

By default, more assumes that Unicode characters are little-endian. If a byte-order marker is 

present, that is used to determine the byte order for the characters. You can force Unicode 

characters to be treated as big-endian by specifying -Ub or -UB. Similarly, you can force 

them to be treated as little-endian by specifying -Ul or -UL. 

displays all backspaces as ^H. Normally characterbackspace_(underscore) displays 

character as underlined and characterbackspacecharacter displays character as boldfaced. 

-u also displays all carriage returns as ^M. This option cannot be used with -A. 

Interactive Commands 

more also accepts the following interactive commands. 

[n]b 

[n]CTRL-B 

[n]PgUp 

moves backward n lines, with a default of one page. If n is more than the page size, more 

displays only the final page. 

[n]d 

[n]CTRL-D 

scrolls forward n lines, with a default of one half of the page size. If you specify n, it 

becomes the new default for subsequent d and u commands. 

[n]f 

[n]CTRL-F 

[n]PgDn 

moves forward n lines, with a default of one page. At end-of-file, more continues with the 

next file in the list, or exits if the current file is the last one in the list. 

[n]G 

[n]g 

h 

[n]j 

[n]SPACE 

[n]ENTER 

goes to the nth line in the file. If you do not specify n, more advances to the end of the file. 

goes to the nth line in the file, with the default being the first line of the file. 

displays a summary of interactive commands. 

395 of 457

[n]• 

[n]k 

[n]• 

scrolls forward n lines, with a default of one line for j, ENTER and •, and a default of one 

page for SPACE. This command displays the entire n lines even if n is more than the page 

size. At end-of-file, these commands cause more to begin displaying the next file in the list, 

or to exit if the current file is the last one in the list. 

scrolls backward n lines, with a default of one line. This command displays the entire n lines 

even if n is more than the page size. 

mletter 

marks the current position with the lowercase letter. When you view a new file, all previous 

marks are lost. 

[n]N 

[n]n 

q 

:q 

ZZ 

R 

repeats the previous search, but in the opposite direction. If you specify n, more repeats the 

search n times. 

repeats the previous search. If you specify n, more repeats the search n times. 

For example, if there are eight occurrences of pattern in the file and /pattern found the 

second occurrence, a follow-up command of 5n finds and sets the current position to the 7th 

occurrence of pattern. 

exits more. 

refreshes the screen and discards any buffered input. 

r 

CTRL-L 

refreshes the screen. 

[n]s 

skips forward n lines (with a default of one line) and displays one page beginning at that 

point. If n would cause less than a full page to be displayed, more displays the last page in 

the file. 

396 of 457

[n]u 

[n]CTRL-U 

scrolls backward n lines, with a default of one half of the page size. If you specify n, it 

becomes the new default for subsequent d and u commands. 

v 

invokes an editor to edit the current file. more uses the editor named by the environment 

variable EDITOR. The default editor is vi. 

'letter 

returns to the position marked with letter. 

'' 

returns to the position where you last issued a movement command of greater than one 

page or the beginning of the file if you have issued no such commands. 

:e [filename]ENTER 

stops viewing the current file and views filename instead. If you do not specify filename, 

more returns to the beginning of the current file. If filename is #, more returns to the last file 

viewed before the current one. 

[n]:n 

[n]:p 

views the next file from the list given on the command line. If you specify n, more views the 

nth next file from the list. 

views the previous file from the list given in the command line. If you specify n, more views 

the nth previous file from the list. 

:t tagname 

goes to tagname (see ctags). 

:w filename 

writes the contents of the current file to the file filename. 

!sh_cmd 

escapes to shell and executes sh_cmd as a shell command. 

= 

CTRL-G 

displays, where possible, the name of the file currently being viewed, its number (relative to 

the total number of files specified in the command line), the current line number, the current 

byte number, the total bytes to display and what percentage of the file has been displayed. 

397 of 457

[n]/[!]pattern 

searches forward in the file for the nth line containing pattern. n defaults to one if not 

specified. If pattern is the null regular expression (/), more uses the previous pattern. If the 

character ! precedes pattern, more searches for lines that do not contain pattern. 

[n]?[!]pattern 

searches backward in the file for the nth line containing pattern. The search begins at the 

line immediately before the top line displayed. n defaults to one if not specified. If pattern is 

the null regular expression (?), more uses the previous pattern. If the character ! precedes 

pattern, more searches for lines that do not contain pattern. 

HOME 

END 

goes to the first line in the file. 

goes to the last line in the file. 


COLUMNS 

contains the maximum number of columns to display on one line. 

EDITOR 

contains the name of the editor that the v command invokes. 

LINES 

contains the number of lines in a page. This value takes precedence over the value provided 

by TERM; however, the -n value takes precedence over the LINES value. 

MORE 

contains a list of options (from those listed in the Options section) as they would appear on 

the command line. This variable takes preference over the TERM and LINES variables. 

TERM 

contains the name of the terminal type. 

DIAGNOSTICS 


398 of 457

0 

>0 



PORTABILITY 

— filename not a text file 

— -n option too large 

— syntax error in regular expression 

— inability to create a file 

— inability to open input file 

— insufficient memory 

— invalid command 

— inability to access the terminal 

— missing string after -p option 



The -A, -P and -S options, and the :w and ! commands are extensions to the POSIX standard. 

The HOME, END, PgDn, PgUp, • and • commands are extensions to traditional implementations of 

more, available only on terminal types that support these keys. 

NOTE 

The MKS more command should not be confused with any more commands supplied with your 

operating system. 

AVAILABILITY 











399 of 457

SEE ALSO 

Commands: 

cat, ctags, pg, vi 

400 of 457

NAME 

ln — create a link to a file 

SYNOPSIS 

ln [-fiRrv] old new 

ln [-fiRrsv] old old ... dir 

DESCRIPTION 

ln 

ln creates a link to a file or set of files. A link is a new directory entry that refers to the same file, 

either in the directory that currently contains the file or in a different directory. The result is a new 

path name that refers to the file. You can access the file under the old path name or the new one; 

both path names are of equal importance. If you rm either name, the other one remains and the file 

contents are still available under that name. The contents of the file do not disappear until you 

remove the last link. 

Note: 

The link utility only works on NTFS file systems on Windows NT/2000/XP/2003. 

A file may have any number of links to it. Thus you can establish any number of different path 

names for any file. 

In the first form given in the synopsis, new becomes a new path name for the file old. In the second 

form, ln creates entries for all the old files under the directory dir. For example, 

ln yourdir/* mydir 

creates links under mydir to all the files under yourdir. The files have the same names under 

mydir that they had under yourdir. ln always assumes this directory form when the last 

operand on the command line is the name of a directory. In this case, none of the old names may 

be a directory. 

In some cases a file may have the same name as the link you are trying to set up. This file is 

referred to as the conflicting path name. To deal with a conflicting path name, ln follows these 

steps. 

● If you have specified -i, ln writes a prompt to standard error to ask if you want to remove 

401 of 457

the conflicting path name. If you answer affirmatively, ln attempts to remove it. 

● If you have specified -f, ln attempts to remove the conflict silently. 

● Otherwise, ln prints a diagnostic message. 

● If it is going to get rid of the conflicting path name, ln attempts to do so in the same way that 

rm does. ln deletes the file associated with the path name if this path name is the last link 

to the file. If ln can't get rid of the conflicting path name, it does not attempt to establish the 

new link; it simply prints an error message on the standard error and goes on to process any 

other files. 

● If ln successfully removes the conflicting path name, it then establishes the link. 

Options 

-f 

-i 

-R 

-r 

-s 

removes conflicting path names without asking for confirmation. 

checks with you before getting rid of conflicting path names. (Note that the -f option 

overrides the -i option.) 

links files recursively; that is, you can link an entire hierarchy of subdirectories at once. 

is identical to -R. 

creates a symbolic link. You can only create symbolic links on Windows 2000/XP/2003 

systems using the NTFS file system and only for directories on local drives. You cannot 

create a symbolic link for a file. 

Note: 

The -s option does not work with drives which use removable media (for example, 

CD drives and tape drives). 

A symbolic link is a pointer to the directory to which it is linked. Like a normal hard link, you 

can refer to the directory by either its original name or the name of the symbolic link. Unlike 

a normal hard link, deleting the original directory leaves a link pointing nowhere and the 

contents of the directory are gone. Deleting the original directory leaves a link pointing 

402 of 457

-v 

nowhere. 

Note: 

When using Explorer, selecting a symbolic link and dragging it to the Recycle Bin (or 

hitting the DELETE key) deletes just the symbolic link. Selecting a symbolic link and 

hitting the SHIFT-DELETE key combination deletes both the symbolic link and the 

original directory and its contents (including any subdirectories). Using the Windows 

command line del command to delete a symbolic link deletes the symbolic link and 

the contents (excluding subdirectories and their contents) of the original directory, but 

not the original directory itself. 

shows file names as they are processed. 

DIAGNOSTICS 


0 

1 

2 

All requested links were established successfully. 


— an argument had a trailing / but was not the name of a directory 

— a file could not be found 

— an input file could not be opened for reading 

— an output file could not be created or opened for output 

— the new link file already exists 

— a link could not be established 

— a read error occurred on an input file 

— a write error occurred on an output file 

— the input and output files were the same file 

— inability to access a file when using -r 

— inability to read a directory when using -r 

— inability to create a directory when using -r 

— a target is not a directory when using -r 

— source and destination directory are the same when using -r 


— invalid command line option 


403 of 457

PORTABILITY 

— a target that should be a directory but isn't 

— no space left on target device 


— unable to create a directory to hold a target file 

POSIX.2. x/OPEN Portability Guide 4.0. All UNIX systems. Windows NT 4.0. Windows 2000. 

Windows XP. Windows Server 2003. 

Only the -f option is part of the POSIX standard. 

AVAILABILITY 











SEE ALSO 

Commands: 

cp, mv, rm 

404 of 457

NAME 

make 

make — maintain program-generated and interdependent files 

SYNOPSIS 

make [-EeiMnpqrstuVvx] [-k|-S] [-c dir] [-f file] [-D macro definition ...] [macro definition ...] 

[target ...] 

DESCRIPTION 

make is a command that helps you manage projects that contain a set of interdependent files. 

Typical examples would be a program with many source and object files, or a document that is built 

from source files, macro files, and so on. make keeps all the files up-to-date with one another: if 

one file changes, make updates all the other files that depend on the changed file. 

Note: 

Options 

-c dir 

This implementation of make features the .POSIX special target to provide maximum 

portability. When you specify this target, make processes the makefile as specified in the 

POSIX.2 standard. For details, see the description of .POSIX in the Special Target 

Directives section of this reference page. 

attempts to change to the specified directory upon startup. If make cannot change the 

directory, it displays an error message. This is useful for recursive makefiles when building 

in a different directory. 

-D macro definition 

defines macro on the command line before reading any makefile. Use the same form as a 

normal macro definition (macro=string). If you use this option, make assigns the value to the 

macro before reading the makefile; any definition of the same macro contained in the 

makefile supersedes this definition. Note that make uses any macros defined in this way 

before it reads any makefile, including the startup file. This allows you to define a startup file 

by providing a value for MAKESTARTUP on the command line: 

make -D MAKESTARTUP=$HOME/project/startup.mk 

405 of 457

-E 

-e 

-f file 

-i 

-k 

-M 

-n 

-p 

-q 

suppresses the reading of the environment completely. 

reads the environment after reading the makefile. If you do not specify -E or -e, make reads 

the environment before reading the makefile, except for the SHELL environment variable, 

which you must explicitly import. This option does not affect the value of MAKEFLAGS. 

uses file as the makefile, ignoring the makefiles specified as prerequisites to the 

.MAKEFILES special target. If you specify file as dash (-), make reads from standard input. 

ignores all errors and continues making other targets. This is equivalent to the .IGNORE 

attribute or macro. 

makes all independent targets, even if an error occurs. If you specify -k, make ignores the 

error and continue to make as much as possible. make does not attempt to update anything 

that depends on the target that was being made when the error occurred. 

does not copy macro definitions from the command line and the MAKEFLAGS environment 

variable to the MAKEFLAGS macro. 

displays the commands that make would execute to update the chosen targets, but does not 

actually execute any recipe lines unless they have a plus sign (+) command prefix. make 

displays recipe lines with an at sign (@) command prefix on the standard output. 

With group recipes, make displays the commands it uses to update a give target, but it also 

executes the commands. 

If make finds the string $(MAKE) in a recipe line, it expands it, adds -n to the MAKEFLAGS, 

and then executes the recipe line. This allows you to see what recursive calls to make do. 

The output correctly shows line breaks in recipes that are divided into several lines of text 

using the \ sequence. 

displays the digested makefile, including macro and target definitions, in a human readable 

form useful for debugging. make itself cannot read this output as an input file. 

406 of 457

-r 

-S 

-s 

-t 

-u 

-V 

-v 

-x 

Targets 

checks whether the target is up-to-date. If it is, make exits with a status of 0; otherwise, it 

exits with a status of 1 (typically interpreted as an error by other software). make does not 

run commands associated with the target unless they start with a plus sign (+) command 

prefix. 

does not read the default rules from the startup file. 

terminates make if an error occurs when bringing a target up-to-date (opposite of -k). This 

is the default. 

does not display recipe commands, warning messages, or touch messages (see the -t 

option). This is equivalent to the .SILENT attribute or macro. 

touches the targets to mark them as up-to-date, but only execute commands to change a 

target if the target has a plus sign (+) command prefix. make does not touch up-to-date 

targets or targets that have prerequisites but do not have recipes. make displays a message 

for each touched target file indicating the file name. 

forces an unconditional update: make behaves as if all the prerequisites of the given target 

are out-of-date. 

displays the version number of make and a list of built-in rules. 

displays a detailed account of make's progress, including files read, definition and 

redefinition of each macro, meta-rule and suffix rule searches, and other information. 

exports all macro definitions to the environment. This happens before make begins making 

targets (but after it reads the entire makefile). 

A target is normally a file that you want to ensure is up-to-date with the files that it is dependent on. 

For example, you may want to check to see if a is based on the most recent version of the 

corresponding source code and if not, recompile the source code to get an up-to-date version. In 

this case, the compiled program file is the target and the corresponding source code files are 

407 of 457

prerequisites (that is, the files a target is dependent on). 

make updates all targets that are specified on the command line. If you do not specify any target, 

make updates the targets in the first rule of the makefile. A target is out-of-date if it is older than 

any of its prerequisites (based on modification times) or if it does not exist. To update a target, 

make first recursively ensures that all the target's prerequisites are up-to-date, processing them in 

the order they appear in the rule. If the target itself is out-of-date, make then executes the recipe 

associated with the target. If the target has no associated recipe, make considers it up-to-date. 

make also supports another form of targets, known as special targets, described in the following 

Special Target Directives section. 

Makefiles 

A makefile is a text file that describes the dependencies between various files. A makefile normally 

contains a list of targets and identifies the prerequisites each depends on. It also contains a series 

of instructions, called recipes that describe the actions to be taken if a given target is out-of-date 

with its prerequisites. 

By default, if you do not specify the -f option, make looks for a file in your current directory named 

makefile. If make does not find this file, and if your file system supports mixed case file names, it 

searches your current directory for a file named Makefile. If make finds either file, it uses this file 

as your makefile. 

You can change the default makefiles with the .MAKEFILES special target. This target is already 

specified in the startup.mk file. See the following Special Target Directives section for more 

information. 

Macro Definitions 

Macro definitions may take several forms. 

macro = string 

is the usual form. If string contains macro references, make does not expand them when the macro 

is defined, but when the macro is itself expanded. 

macro := string 

expands macros inside string before assigning the value to macro. 

macro += string 

408 of 457

appends string to the previous value of macro. 

You can use any amount of white space on both sides of macro operators. make defines the name 

macro to have the value string and replaces it with that value whenever it is used as $(macro or 

${macro} within the makefile. It is possible to specify a $(macro_name or ${macro_name} 

macro expansion where macro_name contains more $(...) or ${...} macro expansions itself. 

Normally, make does not include white space at the beginning and end of string in the definition of 

macro; however, it never strips white space from macros imported from the environment. 

If you want to include white space in a macro definition specified on the make command line, you 

must enclose the definition in quotes (" "). 

make defines macros in the following order: 

Note: 

1. Macro definitions in the built-in rules. 

2. Macro definitions on the command line associated with the -D option. 

3. Macro definitions in startup files. 

4. Contents of the environment. 

5. Macro definitions in the makefiles (in the order they appear). 

6. Macro definitions on the command line without the -D option. 

If you specify the -e option, make reads the makefiles before reading the contents of the 

environment. If you specify the -E option, make does not read the contents of the 

environment. 

If a macro is already defined when make encounters a new definition for it, the new definition 

replaces the old one. For example, a macro definition for name on the command line (without -D) 

overrides a definition for name in the makefile. You can use the -v option to display macro 

assignments, as make performs them. 

Macro Modifiers 

MKS Make supports macro expansions of the form: 

$(macro_name:modifier_list:modifier_list:...) 

Possible modifiers are: 

^"string" 

prefix tokens 

409 of 457

+"string" suffix tokens b file portion of all path names, without suffix d directory portion of all 

path names f file portion of all path names, including suffix l all characters mapped to 

lowercase s/pat/string/ simple pattern substitution; any character can be used to separate 

the pattern from the substitution text suffix=string suffix replacement t"separator" 

tokenization with given separator. u all characters mapped to uppercase 

You may specify macro modifiers in either uppercase or lowercase. 

For example, the following macro assignment 

test = D1/D2/d3/a.out f.out d1/k.out 

produces the following expansions: 

$(test:d) -> D1/D2/d3 . d1 

$(test:b) -> a f k 

$(test:f) -> a.out f.out k.out 

${test:DB} -> D1/D2/d3/a f d1/k 

${test:s/out/in/} -> D1/D2/d3/a.in f.in d1/k.in 

$(test:f:t"+") -> a.out+f.out+k.out 

$(test:t"+") -> D1/D2/d3/a.out+f.out+d1/k.out 

$(test:u) -> D1/D2/D3/A.OUT F.OUT D1/K.OUT 

$(test:l) -> d1/d2/d3/a.out f.out d1/k.out 

$(test:^"/rd/") -> /rd/D1/D2/d3/a.out /rd/f.out /rd/d1/k.out 

$(test:+".Z") -> D1/D2/d3/a.out.Z f.out.Z d1/k.out.Z 

Run-time Macros 

Run-time macros can take on different values for each target. 

$@ 

When building a normal target, this macro evaluates to the full name of the target. When 

building a library, it expands to the name of the archive library. For example, if the target is 

mylib(member) 

$@ expands to 

$% 

mylib. 

When building a normal target, this macro evaluates to the full name of the target. When 

building a library, it expands to the name of the archive member. For example, if the target is 

410 of 457

mylib(member) 

$% expands to 

$> 

$* 

$& 

$? 

$^ 

$< 

member 

The name of the library if the current target is a library member. 

The target name with no suffix ($(%:db)) or the value of the stem in a meta-rule. 

The list of all prerequisites, in all rules that apply to the target. In :: rules, this macro 

produces a value identical to the $^ macro. 

The list of all prerequisites that are newer than the target or do not yet exist and need to be 

built. In rules using the :: rule operator, this macro expands to the same value as $

The construct may be modified: 

fred.obj : $$(@:b).c 

If you are building a library, $$% stands for the name of the archive member being made. If you are 

building a normal target, $$% stands for the name of the target currently being made. 

$$* stands for the name of the current target being made, but with no suffix. 

If you are building a library, $$> stands for the name of the archive library being made. If you are 

not building a library, its use is invalid. 

Comments 

Comments begin with the number sign (#) character and extend to the end-of-line. make discards 

all comment text. 

Makefile Contents 

Inside makefiles, you can split long lines over several lines of text. To do this, put a backslash (\) 

at the very end of the line. You can use this technique to extend comments as well as recipe lines 

and macro definitions for example. 

If a rule or macro definition must contain a # character, use \#; otherwise, make mistakes the # for 

the beginning of a comment. Also, if a macro definition must contain a single $ character, use $$. 

File names that contain a colon (:) must always be enclosed in quotes (" "): 

"a:target" : "a:prereq" 

Rules 

The general format of a rule is 

targets [attributes] ruleop [prerequisites] [;recipe] 

{ recipe} 

The parts of the rule are described as follows. 

targets 

one or more target names. 

attributes 

412 of 457

a list, possibly empty, of attributes to apply to the list of targets. 

ruleop 

an operator token, usually :, that separates the target names from the prerequisite names 

and may also affect the processing of the specified targets. 

prerequisites 

a list of zero or more names the specified targets depend on. 

recipe 

command to execute to update targets. It may follow on the same line as the prerequisites, 

separated from them by a semicolon (;). If such a recipe is present, make takes it as the 

first in the list of recipe lines defining how to make the named targets. Additional recipe lines 

may follow the first line of the rule. Each subsequent recipe line must begin with a tab 

character. 

The possible rule operators are described here: 

targets : prereqs 

simple rule definition. For explicit targets, at most one simple rule may have a recipe, in 

contrast with the :: rule operator, whose description follows. 

targets :! prereqs 

executes the recipe for the associated targets once for each out-of-date prerequisite. In 

simple rules, the recipe is executed only once, for all out-of-date prerequisites at the same 

time. The $< macro expands to the current prerequisite if it appears in rules with this rule 

operator. 

targets :^ prereqs 

inserts the specified prerequisites before any other prerequisites already associated with the 

specified targets. 

targets :- prereqs 

clears the previous list of prerequisites before adding the new prerequisites. 

targets :: prereqs 

is used for multiple rules applying to the same target. Each rule can specify a different set of 

prerequisites with a different recipe for updating the target. Each rule is treated 

independently; the target is remade for each rule with out-of-date prerequisites, using the 

corresponding recipe. 

targets :| prereqs 

can only be used in meta-rules. It tells make to treat each meta-dependency as an 

413 of 457

independent meta-rule. For example: 

%$O :| archive/%.c rcs/%.c /srcarc/RCS/%.c 

recipe... 

is equivalent to 

%$O : archive/%.c 

recipe... 

%$O : rcs/%.c 

recipe... 

%$O : /srcarc/rcs/%.c 

recipe... 

This operator is particularly useful for searching for MKS Source Integrity archives. If the 

RCSPATH variable used by MKS Source Integrity is defined as 

archive/%f;rcs/%f;/srcarc/rcs/%f 

then the meta-rule 

% :| $(RCSPATH:s/%f/%/:s/;/ /) 

co -l $< 

searches the path looking for an RCS file and checks it out. 

Circular Dependencies 

There are two types of circular dependencies: within-rule and between-rule. A within-rule circular 

dependency occurs when the target's name is included in the list of prerequisites for that target. 

For example, 

c.o : a.o b.o c.o 

is a within-rule circular dependency. make detects a within-rule circular dependency when it is 

parsing the makefile to build the dependency tree. 

A between-rule circular dependency occurs when you have two targets, each of which includes the 

other's name in its prerequisite list. For example, 

a.o : b:o 

b:o : a.o 

414 of 457

is a between-rules circular dependency. make detects a between-rule circular dependency when it 

is processing the dependency tree built during the parse phase. 

Normally make only detects circular dependencies for those targets actually being built. When a 

circular dependency is encountered, make issues a warning message, removes the offending 

prerequisite from the list, and continues parsing the makefile. The .CYCLECHECK special target 

can be used to alter make's treatment of circular dependencies. For details, see the Special Target 

Directives section of this reference page. 

Recipes 

You can use a target that has prerequisites but no recipes to add the given prerequisites to that 

target's list of prerequisites. 

You may preface any recipe line with a command prefix immediately following the character 

(-, @, + or all three). - indicates that make is to ignore non-zero exit values when it executes this 

recipe line. @ indicates that make is not to display the recipe line before executing it. + tells make to 

always execute this line, even when -n, -q, or -t is specified. 

Group recipes begin with [ in the first non-white space position of a line, and end with ] in the first 

non-white space position of a line. Recipe lines in a group recipe need not have a leading tab. 

make executes a group recipe by feeding it as a single unit to a shell. If you immediately follow the 

[ at the beginning of a group recipe with one of -, @ or +, they apply to the entire group in the 

same way that they apply to single recipe lines. 

Inference Rules 

With inference rules, you can specify general rules for building files rather than creating a specific 

rule for each target. 

MKS Make provides two forms of inference rules: suffix rules and meta-rules. MKS Make includes 

suffix rules to ensure compatibility with older makefiles. Meta-rules, however, provide a more 

general mechanism for specifying make's default behavior. They provide a superset of the 

functionality of suffix rules. make searches all meta-rules before using suffix rules. 

make uses the inference rules to infer how it can bring a target up to date. A list of inference rules 

defines the commands to be executed. The default startup.mk contains a set of inference rules 

for the most common targets. You can specify additional rules in the makefile. 

When make finds no explicit target rule to update a target, it checks the inference rules. If make 

finds an applicable inference rule with an out-of-date prerequisite, it executes that rule's recipe. 

(See also the section describing the .DEFAULT special target). 

Meta-rules 

415 of 457

Meta-rules have one target with a single percent symbol % that matches an arbitrary string called 

the stem. The % in a dependency stands for the stem. 

The inference rule to update a target matching pattern p1%s1, where p1 and s1 are prefix and 

suffix strings of the target, having a prerequisite p2%s2, where % is the stem from the target, is 

specified as follows: 

p1%s1 : p2%s2 ; recipe... 

Either the prefix or suffix string may be empty. 

Transitive Closure 

Meta-rules provide a mechanism that allows several meta-rules to chain together to eventually infer 

all the needed prerequisites to create the target. 

This is called transitive closure. For example, suppose you have the following two meta-rules 

%$O : %.c 

... rule body... 

%.c : %.y 

... rule body ... 

When you specify 

make file.obj 

make uses the first meta-rule to look for file.c. If it cannot find an explicit rule to build file.c, it 

again looks through the meta-rules for a rule to build %.c. It finds such a rule in 

%.c : %.y 

Thus, make can rebuild file.obj from file.y. 

make considers each meta-rule only once when performing transitive closure to avoid a situation 

where it loops forever. For example, if you have the rule 

% : %.c 

the command 

... rule body ... 

416 of 457

make file 

causes make to look for file.c. If the meta-rules were not restricted and file.c did not exist, 

then make would look for file.c.c, and then file.c.c.c, and so on. Because make uses each 

meta-rule only once, this cannot happen. 

make computes transitive closure once for each meta-rule head the first time the pattern matches a 

target. When transitive closure is computed, make adds all the computed rules to the rule set for 

that meta-rule head. For example, if you have the rules 

%$E : %$O 

recipe 1... 

%$O : %c 

recipe 2... 

and you are making file.exe, this target matches successfully against %$E causing make to 

compute transitive closure for %$E. As a result of this computation, a new rule is created: 

%$E : %.c 

recipe 2... 

recipe 1... 

.REMOVE target recipe for %$O, if not .PRECIOUS 

make executes this rule if file$O.obj does not exist. When make finishes the computation for the 

rule head, it marks the rule head as transitive closure computed. Since make adds all possible new 

rules to the rule set the first time the computation is done, it is not necessary to do it again -- 

nothing new is added. 

The best way to understand how this works is to experiment with little make files with the -v option 

specified. This shows you in detail what rules are being searched, when transitive closure is 

calculated and what rules are added. 

Order of Rule Generation 

Since transitive closure allows make to generate new rules, it is important to understand the order 

this is done in: 

1. make searches for explicit rules in the order they appear, so explicit rules always take 

precedence. 

2. make reads meta-rules in the order they appear in the makefile. The first rule that appears in 

the makefile is the first one checked. 

3. New explicit meta-rules (as distinct from meta-rules generated by transitive closure) replace 

old ones. In other words, if your makefile contains an explicit rule like this one, it replaces 

417 of 457

the default rule in startup.mk: 

%$O : %.c 

rule1 

If you use the -v option, make prints a warning when it replaces a meta-rule. 

4. When transitive closure is calculated, the new meta-rules generated are added to the end of 

the list of possible meta-rules. Thus, make always finds the explicit rules first, so they take 

precedence over generated rules. You can use the -v option to see what rules make 

generates and the order they appear in. 

5. make performs two passes through the rules. On the first pass it attempts to find a match 

with an explicit rule in the makefile; if this does not succeed, make performs a second pass 

to find a match with an existing file. 

Suffix Rules 

make treats targets that begin with a period and contain no slashes or percent signs as suffix rules. 

If there is only one period in the target, it is a single-suffix inference rule. Targets with two periods 

are double-suffix inference rules. Suffix rules do not have prerequisites but do have commands 

associated with them. 

When make finds no explicit rule to update a target, it checks the suffix of that target (.s1) against 

the suffix rules. make examines a prerequisite based on the base name of the target with the 

second suffix (.s2) appended, and if the target is out-of-date with respect to this prerequisite, make 

executes the recipe for that inference rule. 

If the target to be built does not contain a suffix and there is no rule for the target, make checks the 

single suffix inference rules. The single suffix inference rules define how to build a target 'br 'ne 5v 

if make finds a rule with one of the single suffixes appended. A rule with one suffix .s2 defines how 

to build target from target.s2. 

Any suffixes used in a suffix rule must appear as a prerequisite of the special target .SUFFIXES. 

The order that the suffixes appear in the .SUFFIXES rule determines the order make checks the 

suffix rules in. New suffixes and suffix rules are added to the existing list. To turn off the suffix 

rules, place 

.SUFFIXES: 

in your makefile. This clears the prerequisites of the .SUFFIXES target and prevents the enaction 

of any suffix rules. 

The search algorithm used for suffix rules depends on whether or not the .POSIX special target is 

418 of 457

specified. When .POSIX is specified, the following steps describe the search algorithm for suffix 

rules: 

1. Extract the suffix from the target. If that target has no suffix, go to step 6. 

2. Is it in the .SUFFIXES list? If not, then quit the search. 

3. If it is in the .SUFFIXES list, look for a double suffix rule that matches the target suffix. 

4. If you find one, then extract the base name of the file, add on the second suffix and see if 

the resulting file exists. If it does not, then keep searching the double suffix rules. If it does 

exist, then use the recipe for this rule. 

5. If no successful match is made, then the inference has failed. 

6. If the target did not have a suffix, then check the single suffix rules in the order that the 

suffixes are specified in the .SUFFIXES target. 

7. For each single suffix rule, add the suffix to the target name and see if the resulting file 

name exists. 

8. If the file exists, then execute the recipe associated with that suffix rule. If the file does not 

exist, continue trying the rest of the single suffix rules. 


When the .POSIX special target is not specified, make handles suffix rules in the same manner as 

traditional implementations of make. The following steps describe the search algorithm for suffix 

rules in this situation. 

1. Extract the suffix from the target. If that target has no suffix, go to step 8. 

2. Is it in the .SUFFIXES list? If not, then quit the search. 

3. If it is in the .SUFFIXES list, look for a double suffix rule that matches the target suffix. 

4. If you find one, then extract the base name of the file, add on the second suffix and see if 

the resulting file exists. If it does, go to step 7. If not, continue with step 5. 

5. Is there an inference rule for the resulting file? If yes, execute the recipe associated with that 

rule (that should describe how to make the file exist) and go to step 7. 

6. Search for the next double suffix rule that matches the target suffix and return to step 4. If 

the double suffix rules are exhausted then the inference has failed. 

7. Use the recipe for the target rule. 

8. If the target did not have a suffix, then check the single suffix rules in the order that the 

suffixes are specified in the .SUFFIXES target. 

9. For each single suffix rule, add the suffix to the target name and see if the resulting file 

name exists. 

10. If the file exists, then execute the recipe associated with that suffix rule. If the file does not 

exist, continue trying the rest of the single suffix rules. 


MKS Make also provides a special feature in the suffix rule mechanism for archive library handling, 

useful mainly for compatibility with System V Make. If you specify a suffix rule of the form 

.suf.a: 

419 of 457

ecipe 

the rule matches any target specified as a library member, regardless of what the actual library 

suffix is. For example, suppose your makefile contains the following rules: 

.SUFFIXES: .a .obj 

.obj.a: 

echo adding $< to library $@ 

If mem.obj exists, then the following command 

make -r "mylib(mem)" 

causes make to print this message: 

adding mem.obj to library mylib 

Refer to Making Libraries in the User's Guide for more information about libraries. 

Attributes 

make defines several target attributes. Attributes may be assigned to a single target, a group of 

targets, or to all targets in the makefile. Attributes affect what make does when it needs to update a 

target. You can associate attributes with targets by specifying a rule of the following form: 

attribute_list : target ... 

This assigns the attributes in attribute_list to the given targets. If you do not specify any targets, the 

attributes apply to every target in the makefile. You can also put attributes inside a normal rule, as 

in: 

targets attribute_list : prerequisite ... 

These are the recognized attributes: 

.EPILOG 

Insert shell epilog code when executing a group recipe associated with any target having 

this attribute set. 

.IGNORE 

Ignore an error when trying to make any target with this attribute set. 

420 of 457

.LIBRARY 

Target is a library. 

.PRECIOUS 

Do not remove this target under any circumstances. Any automatically inferred prerequisite 

inherits this attribute. 

.PROLOG 

Insert shell prolog code when executing a group recipe associated with any target having 

this attribute set. 

.SETDIR 

Change current working directory to specified directory when making associated targets. 

The syntax of this attribute is .SETDIR=path, where path is the path name of desired 

working directory. If path contains any colon (:) characters, the entire attribute string must 

be quoted, not just the path name. 

.SILENT 

Do not echo the recipe lines when making any target with this attribute set, and do not issue 

any warnings. 

You can use any attribute with any target, including special targets. 

Special Target Directives 

Special Target Directives are called targets because they appear in the target position of rules; 

however, they are really keywords, not targets. The rules they appear in are directives that control 

the behavior of make. 

The special target must be the only target in a special rule--you cannot list other normal or special 

targets. 

Some special targets are affected by some attributes. Any special target can be given any 

attribute, but often the combination is meaningless and the attribute has no effect. 

.BRACEEXPAND 

This target may have no prerequisites and no recipe associated with it. If set, the target 

enables the outdated brace expansion feature used in older versions of MKS Make. (This 

target is ignored if the .POSIX special target is set.) Older versions of make use brace 

expansion to expand a token list of this form: 

string1{token_list}string2 

421 of 457

make adds string1 to the front, and string2 to the end, of each token in the token_list. To include 

brace brackets while this target is set, use {{ and }}; you cannot include literal brace brackets in 

the token list. You can achieve the same kind of brace expansion in modern versions of make by 

using macro expansion with prefix and suffix modifiers: 

$(TOKEN_BASE:^"prefix":+"suffix") 

Note that the double quotes are required. Future versions of MKS Make may dispense with brace 

expansion completely. 

.CYCLECHECK 

This special target may have no prerequisites and no recipe associated with it. If set, it 

determines how make treats circular dependencies (for more information, see the Circular 

Dependencies section of this reference page). You can specify one of five attributes with 

this target. If you specify more than one attribute, an error message results. The five 

attributes are: 

.SILENT 

make remains silent about any within-rule and between-rule circular dependencies, removes 

the offending dependency from the list of prerequisites, and continues. 

.WARNTARG 

make issues warnings for named targets with circular dependencies. If the name of the 

dependency is the same as the named target, it is removed from the list of prerequisites and 

make continues. This is the default behavior if .CYCLECHECK is not specified or is specified 

with no attributes. 

.WARNALL 

make issues warnings for all within-rule circular dependencies regardless of whether the 

target is being built or not and for all between-rule circular dependencies for the named 

targets. The offending dependency is removed from the list of prerequisites and make 

continues. 

.FATALTARG 

make treats all circular dependencies for named targets as fatal errors. It issues an error 

message and exits. 

.FATALALL 

make treats all within-rule circular dependencies as fatal errors whether the target is being 

built or not. It also treats all between-rule circular dependencies for named targets as fatal 

errors. make issues an error message and exits. 

For example, to set the circular dependency check to make's default, use the rule: 

422 of 457

.CYCLECHECK .WARNTARG: 

.DEFAULT 

This target has no prerequisites, but it does have a recipe. If make can apply no other rule to 

produce a target, it uses this rule if it has been defined. 

.ERROR 

make executes the recipe associated with this target whenever it detects an error condition. 

.EXPORT 

All prerequisites associated with this target that correspond to macro names are exported to 

the environment at the point in the makefile where this target appears. If you do not specify 

any prerequisites for this target, all macros are exported. 

.GROUPEPILOG 

make adds the recipe associated with this target after any group recipe for a target that has 

the .EPILOG attribute. 

.GROUPPROLOG 

make adds the recipe associated with this target before any group recipe for a target that 

has the .PROLOG attribute. 

.IMPORT 

make searches in the environment for prerequisite names specified for this target and 

defines them as macros with their value taken from the environment. If the prerequisite 

.EVERYTHING is given, make reads in the entire environment (also, see the -e and -E 

options). 

.INCLUDE 

make reads one or more additional makefiles (specified in the prerequisite list), as if their 

contents had been inserted at this point. If the prerequisite list contains more than one file, 

make reads them in order from left to right. 

make uses the following rules to search for extra makefiles: 

● If a relative file name is enclosed in quotes, or is not enclosed with angle brackets (< 

and >), make looks in the current directory. If the file is not present, make then looks 

for it in each directory specified by the .INCLUDEDIRS special target. 

● If a relative name is enclosed with angle brackets (< and >), make only searches in 

the directories specified by the .INCLUDEDIRS special target. 

● If an absolute path name is given, make looks for that file, and ignores the list 

associated with the .INCLUDEDIRS special target. 

423 of 457

.INCLUDEDIRS 

The list of prerequisites specified for this target defines the set of directories to search when 

including a makefile. 

.MAKEFILES 

The list of prerequisites is the set of files to try to read as the user makefile. These files are 

made in the order they are specified (from left to right) until one is found to be up to date. 

This is the file that is used. 

.NOAUTODEPEND 

Disable the autodependency feature when building libraries. When this special target is 

used, only library members that have been explicitly given as dependents are considered 

prerequisites. 

.POSIX 

Process the makefile as specified in the POSIX.2 draft standard. This special target must 

appear before the first non-comment line in the makefile, and may have no prerequisite list, 

or recipe, associated with it. The target does the following: 

● causes make to use the shell when executing all recipe lines; make invokes one shell 

per line, regardless of the setting of SHELLMETAS. 

● disables brace expansion (the .BRACEEXPAND special target is ignored). 

● disables meta-rule inferencing. 

● disables conditionals. 

● disables dynamic prerequisites generation for libraries. 

● disables group recipes. 

● disables library autodependency. 

● make does not check for the string $(MAKE) when run with the -n options specified. 

● make always prints a message if no work is done. 

● When attempting to do suffix rule inference, the inference succeeds only if the 

inference prerequisite file exists. 

.REMOVE 

make uses the recipe of this target to remove any intermediate files that it creates if an error 

is encountered before creating the final target. This .REMOVE target only deletes a file that 

satisfies all of the following criteria: 

● the file did not exist when make began running 

● the file is named as an intermediate target, produced by invoking a meta-rule that 

was produced by transitive closure 

● the file is not explicitly named in the makefile 

● the generated target does not have the .PRECIOUS attribute 

● the file is a prerequisite of a rule that is actually used 

.SOURCE 

The prerequisite list of this target defines a set of directories to check when trying to locate a 

424 of 457

target file name. 

.SOURCE.x 

Same as .SOURCE, except that make searches the .SOURCE.x list first when trying to 

locate a file matching a target with a name that ends in the suffix .x. 

.SUFFIXES 

make appends the prerequisite list of this target to the set of suffixes used when trying to 

infer a prerequisite for making a target using suffix rules. If you specify no prerequisites, 

make clears the list of suffixes, effectively disabling suffix rules from that point on. 

Control Macros 

make defines a number of control macros that, like special target directives and attributes, alter its 

behavior. A control macro that has the same function as a special target or attribute also has the 

same name. 

Macros that are said to be defined internally are automatically created by make and you can use 

them with the usual $(name construct. For example, you can use $(PWD) to obtain the current 

directory name. 

Recognized control macros are: 

DIRSEPSTR 

Contains the characters used to separate parts in a path name and can be set by the user. 

make uses the first character in this string to build path names when necessary. 

Note: 

The DIRSEPSTR macro must be set in your environment before running make, so that 

the MAKEDIR macro is aware of its value. This is necessary because MAKEDIR is set 

before the makefile or command-line flags are looked at. 

.EPILOG 

If assigned a non-empty value, the .EPILOG attribute is given to every target. 

GROUPFLAGS 

Specifies options to pass to GROUPSHELL when make invokes it to execute a group recipe. 

GROUPSHELL 

Gives the path name of the command interpreter (shell) that make calls to process group 

recipes. 

GROUPSUFFIX 

425 of 457

Specifies a string for make to use as a suffix when creating group recipe files to be handed 

to the command interpreter. This must be .bat (for command.com) or .cmd (for cmd.exe). 

.IGNORE 

If this is assigned a non-null value, make assigns the .IGNORE attribute to every target. 

INCDEPTH 

The current depth of makefile inclusion. This is set internally. 

MAKE 

This is set by the startup file and may be changed by the user. The standard startup file 

defines it as 

$(MAKECMD) $(MFLAGS) 

The MAKE macro is not used by make itself, but the string $(MAKE) is recognized when using the 

-n option for single line recipes. 

MAKECMD 

The name that make was invoked with. 

MAKEDIR 

Full path name of the initial directory where make began execution. 

MAKEFLAGS 

The MAKEFLAGS macro contains all the options and macros specified in the MAKEFLAGS 

environment variable plus all the options specified on the command line, with the following 

exceptions: 

● The options -c, -D, -f, and -p are silently ignored if they are found in the 

MAKEFLAGS environment variable. 

● Any of options -c, -D, -f, -p, -v, or -V, when specified on the command line, are 

not added to the MAKEFLAGS macro. 

● When the -M option is specified, macro definitions from the MAKEFLAGS 

environment variable are not added to the MAKEFLAGS macro. 

added 

Options in the MAKEFLAGS environment variable may have leading minus signs and can 

be separated by spaces. These are stripped out when the MAKEFLAGS macro is 

constructed. 

Note: 

make always reads the MAKEFLAGS environment variable before reading the 

makefile. The -E and -e options do not affect this. 

426 of 457

MAKESTARTUP 

Has the default value ROOTDIR/etc/startup.mk on Windows systems. (On UNIX and 

POSIX systems, the $ROOTDIR is omitted.) To change this value, you can set the 

MAKESTARTUP environment variable before running make. You can also specify a value 

for this control macro on the command line, if you use the -D option: 

make -DMAKESTARTUP=$HOME/project/startup.mk 

MFLAGS 

Same as MAKEFLAGS, except that it includes the leading switch character. 

NULL 

OS 

Permanently defined to be the empty string. 

Name of the operating system that this version of make is compiled for. 

NT on Windows NT/2000/XP/2003 

unix on UNIX systems 

POSIX on POSIX systems 

.PRECIOUS 

If this is assigned a non-empty value, make assigns the .PRECIOUS attribute to every 

target. 

.PROLOG 

If this is assigned a non-empty value, make assigns the .PROLOG attribute to every target. 

PWD 

Full path name of the current directory where make is executing. 

SHELL 

Specifies the full path name of the command interpreter that make calls to process single 

line recipes if they contain one or more of the characters given in SHELLMETAS. Otherwise, 

make executes these commands directly. By default, the value of the SHELL environment 

variable does not affect the value of this macro; however, you can use the .IMPORT special 

target to assign the environment variable's value to this macro. You can also use the 

EXPORT special target to assign this macro's value to the SHELL environment variable. 

SHELLFLAGS 

Specifies options to pass to the shell when invoking it to execute a single line recipe. 

427 of 457

SHELLMETAS 

Specifies a list of metacharacters that can appear in single recipe lines. If make finds any 

metacharacter, it invokes the recipe using the shell specified by SHELL; otherwise, it 

executes the recipe without the shell. 

.SILENT 

If this is assigned a non-empty value, make assigns the .SILENT attribute to every target. 

SWITCHAR 

The character currently being used to mark options in command lines. 

Making Libraries 

A library is a file containing a collection of object files. To make a library, you specify it as a target 

with the .LIBRARY attribute and list its prerequisites. The prerequisites should be the object 

members that are to go into the library. When make makes the library target, it looks for the 

prerequisites in the library if it cannot find an appropriate object file. 

When make finds lib(member), it declares the lib portion as a target with the .LIBRARY attribute 

and automatically declares the member portion as a prerequisite of the lib target. When make finds 

lib((entry)), it declares the lib portion as a target with the .LIBRARY attribute and automatically 

declares the module defining entry as lib's associated prerequisite. 

This autodependency can be turned off by the .NOAUTODEPEND special target. Since 

autodependency is not POSIX compatible, it is also disabled by the .POSIX special target. 

Conditionals 

Conditional expressions use the following form: 

.IF expression 

... if text ... 

{.ELSIF expression2 

... elsif text ...} 

[.ELSE 

... else text ...] 

.END 

You can nest the conditionals (that is, the text may contain another conditional). The .IF, .ELSE, 

.ELSIF, and .END must start in the first column of the line. expression or expression 2 can have 

one of three forms: 

string 

428 of 457

is true if the given string is non-empty, 

string == string 

is true if the two strings are equal, and 

string != string 

is true if the two strings are not equal. 

Typically, one or both strings contain macros that make expands before comparing. make also 

discards white space at the start and end of the text portion before the comparison. This means 

that a macro that expands to nothing but white space is considered an empty value for the purpose 

of the comparison. If a macro expression needs to be compared to an empty string, compare it to 

the value of the macro NULL for readability. 

The text enclosed in the conditional construct must have the same format that it would have 

outside the conditional. In particular, make assumes that anything that starts with a tab inside the 

conditional is a recipe line. This means that you cannot use tabs to indent text inside the 

conditional (except, of course, for recipe lines that always begin with tabs). 

Functions 

make supports the following function: 

$(shell shell_cmd) 

performs the same function that backquotes (`shell_cmd`) do in most shells. That is, it 

performs command substitution, returning the output of the specified shell command, 

shell_cmd and subsituting it into the surrounding text, after first replacing each newline or 

carrige-return/newline pair with a single space and removing any trailing newline or carriagereturn/newline 

pair. 

The command specified with the shell function is run when the the function call is 

expanded. Because this function involves spawning a new shell, you should carefully 

consider the performance implications of using the shell function within recursively 

expanded variables as opposed to simply expanded variables. 

Software Configuration Management Integration 

make provides integration with a variety of Software Configuration Management (SCM) 

applications. 

The SCM environment variable determines not only if SCM integration is enabled, but also which 

429 of 457

SCM application is to be used. The following are the valid values for SCM: 

CC Rational Clearcase 

CVS CVS (Concurrent Versions System) 

RCS RCS (Revision Control System) 

SIE Source Integrity Enterprise 

SS Microsoft SourceSafe 

If SCM is unset or set to a value other than those listed, no SCM integration is used. 

make uses the $ROOTDIR/etc/makescm.ksh script and the built-in rules in 

$ROOTDIR/etc/startup.mk to determine if a possible prerequisite file name is a versioned 

object in the current SCM repository. When SCM integration is enabled, make checks out and uses 

the most recent version of each prerequisite file on the appropriate branch in the current SCM 

repository. However, if a writable version of the prerequisite file exists in the working directory, a 

newer version is not checked out. To help the SCM application determine the most recent version 

of versioned files, the UPDFLAGS variable in $ROOTDIR/etc/startup.mk can be set to a string 

of options to be used with the SCM application's command for retrieving file versions. 


COFLAGS 

specifies the options to be used with the RCS co command when RCS integration is 

enabled with the HAVERCS environment variable. This variable is supported primarily for 

backwards compatibility with earlier versions of make. You should use the SCM and 

UPDFLAGS environment variables as described in the Software Configuration Management 

Integration section. 

HAVERCS 

when set to yes, enables RCS integration. This variable is supported primarily for 

backwards compatibility with earlier versions of make. You should use the SCM and 

UPDFLAGS environment variables as described in the Software Configuration Management 


Note: 

You should not have both the HAVERCS variable set to yes and the SCM variable 

set to a valid value as this may lead to unexpected results. 

MAKEFLAGS 

contains a series of make options that are used as the default options for any make 

command. You may specify the options with or without leading minus signs (-) and blanks 

430 of 457

etween them. It may also include macro definitions of the form usually found on the 

command line. 

MAKESTARTUP 

contains the path name of the make startup file. By default, make uses the file 

ROOTDIR/etc/startup.mk as its startup file. To use a different file, set this environment 

variable before running make. 

SCM 

when set to an appropriate value, enables Software Configuration Management Integration 

and specifies which SCM application to use. For details on SCM integration and appropriate 

values for this environment variable, see the Software Configuration Management 


Note: 

You should not have both the HAVERCS variable set to yes and the SCM variable 

set to a valid value as this may lead to unexpected results. 

SHELL 

contains the name of a command interpreter. To assign this value to the control macro 

SHELL, use the .IMPORT special target. You can also use the .EXPORT special target to 

assign the value of the SHELL macro to this environment variable for commands run from 

recipes. 

UPDFLAGS 

when SCM integration is enabled, helps the SCM application specified by the SCM 

environment variable determine the most version of a version of version files. This variable 

is set in $ROOTDIR/etc/startup.mk and contains a string of options to be used with the 

SCM application's command for retrieving file versions. For details on SCM integration, see 

the Software Configuration Management Integration section. 

make automatically imports all other environment variables, unless you specify the -E option. 

FILES 

ROOTDIR/etc/makescm.ksh 

is used in conjunction with the built-in rules in ROOTDIR/etc/startup.mks to implement 

SCM integration. See the Software Configuration Management Integration for details. 

ROOTDIR/etc/startup.mk 

default startup file containing default rules. 

431 of 457

DIAGNOSTICS 

If a command in a recipe line fails (exits with a non-zero status), Make returns the exit status of the 

failed command. Since most commands use exit statuses between 0 and 10, Make uses exit 

status values below 10 only for failures that do not run recipe lines. 

Possible exit status values for Make are: 

0 

1 

2 

126 

127 

128 


Returned if you specified -q and file is not up to date. 


— unknown command-line option 

— missing argument to option, such as no file name for -f 

Recipe command not executable. 

Recipe command not found. 

Make called a program that crashed. 

129-254 

Make, or a program that Make called, was interrupted by a signal; the error code is the 

signal number OR'ed with 128. For example, SIGINT ( CTRL-C) is frequently signal 1: the 

return code from Make is 128|1, or 129. 

255 

Failure because of any of the following: 

— Macro cannot be redefined 

— Macro variables must be assigned with := 

— Special target cannot be a prerequisite 

— Too many makefiles specified 

— Configuration file not found 

— No makefile present 

432 of 457

— Missing .END for .IF 

— No target 

— Unable to return to directory 

— Too many open files 

— Open failed 

— File not found 

— Unable to change directory 

— No more memory 

— Line too long 

— Detected circular macro definition 

— Unterminated pattern string 

— Unterminated replacement string 

— Token separator string must be quoted 

— Unterminated separator string 

— Expansion too long 

— Suffix too long 

— Unmatched quote 

— .IF nesting too deep 

— .ELSE without .IF 

— Unmatched .END 

— Inference rules result in circular dependency 

— No macro name specified 

— Write error on temp file 

— Target not found, and cannot be made 

— Do not know how to make 

—

PORTABILITY 

— Include file NAME, not found 

— NAME ignored on special target 

— Attributes possibly ignored 

— Cannot find member defining symbol ((NAME) 

— Invalid library format 

— Cannot touch library member 

— SHELL macro not defined 

— Too many arguments 

— Could not export NAME 

— Cannot open file 

— Detected circular dependency 

— Unable to stat / 

— Unable to stat . 

— Cannot open .. 

— Read error in .. 

— Metarule too long: "rule" 



The following features of MKS Make are enhancements to POSIX.2: 

● The options; -c dir, -D macro_def'n, -E, -M, -u, -V, -v, -x. 

● The -n option has enhanced functionality not covered by the standard; for more information 

see the explanations of the -n option and the .POSIX special target in this reference page. 

● The run-time macros: $&, $^, $>. 

● The dynamic prerequisites: $$%, $$>, $$*, $$@. 

● All macro expansion modifiers except for suffix replacement. 

● Macro assignments of the following forms: 

● Brace expansion. 

● Backslash continuation. 

macroname := stringassigned 

macroname += stringassigned 

● The quoting mechanism, as in the following example: 

"a:target" : "a:prerequisite" 

● All rule operators except the colon (:). 

● Conditionals. 

434 of 457

● Meta-Rules. 

● All MKS Make attributes except .IGNORE, .PRECIOUS, .SILENT. 

● All MKS Make special targets except .DEFAULT, .POSIX, .SUFFIXES. 

● All MKS Make control macros except SHELL (referred to in POSIX.2 as control macros). 

● The search algorithm for suffix rule follows the POSIX.2 rules when the .POSIX special 

target is specified, but behaves like traditional implementations when it is not specified. 

LIMITS 

The maximum length of a script line is 16834 characters. 

In some environments, the length of an argument string is restricted. For example, command-line 

arguments cannot be longer than 128 bytes if you are using the standard command.com command 

interpreter. 

NOTES 

When the .SETDIR special target is used, MKS Make checks the file attributes of targets and 

prerequisites on every pass through a rule. This can significantly increase the number of file 

system accesses. 

AVAILABILITY 








SEE ALSO 


makefile 

Using MKS Make 

435 of 457

NAME 

manstrip 

manstrip — strip the unprintable sequences out of online reference pages 

SYNOPSIS 

manstrip 

DESCRIPTION 

manstrip is a filter. It takes text redirected from a file, or piped into it, and outputs that text to 

standard output, without any ANSI color escape sequences or ^H control sequences. 

This command can be used to produce standard text versions of the online man pages for printing. 

EXAMPLE 

To convert the sh reference page to a regular text file, type the following command: 

man sh.1 | manstrip > sh.txt 

PORTABILITY 

Windows Me. Windows NT 4.0. Windows 2000. Windows XP. Windows Server 2003. 

AVAILABILITY 











436 of 457

SEE ALSO 

Commands: 

man 

437 of 457

NAME 

mv — rename and move files and directories 

SYNOPSIS 

mv [-adfiv] file1 file2 

mv [-fiv] file ... directory 

mv -r [-fiv] directory1 directory2 

DESCRIPTION 

mv 

mv renames files or moves them to a different directory. If you specify multiple files, the target (that 

is, the last path name on the command line) must be a directory. mv moves the files into that 

directory and gives them names that match the final components of the source path names. When 

you specify a single source file and the target is not a directory, mv moves the source to the new 

name, by a simple rename if possible. 

If a destination file exists and you do not have write permission for it, mv prompts with the name of 

the existing file. If you answer y or yes, it deletes the destination and then moves the source. 

If the file being moved is a sparse file and the file system to which it is being moved does not 

support sparse files, mv warns that the resulting file will be larger. If the -i option was also 

specified, mv asks you if want to expand the file or skip it. 

Options 

-a 

moves the ACLs associated with the specified file along with the file itself. When used with 

-p, permissions are moved as well. 

This option is only available on NTFS file systems. 

Note: 

When you use mv to do a simple rename (that is, simply move it on the same device), 

ACLs are automatically moved with the file and the -a option is not required. 

However, when you use mv to move a file to another device, you must specify the -a 

option or the ACLs are not moved with the file. 

438 of 457

-d 

-f 

-i 

-r 

-v 

delays moving the specified files until the system is rebooted. 

On Windows Me, the destination file name must be a short file name. The destination 

directory may have a long file name but the file name must be short. 

This option relies upon the underlying operating system's capability to perform the action at 

reboot time. 

does not ask if you want to overwrite an existing destination without write permission; it 

automatically behaves as if you answered yes. If you specify both -f and -i, mv uses the 

option that appears last on the command line. 

always prompts before overwriting an existing file, whether or not the file is read-only. If you 

specify both -f and -i, mv uses the option that appears last on the command line. 

moves directory and all its contents (files, subdirectories, files in subdirectories, and so on). 

For example, mv -r dir1 dir2 moves the entire contents of dir1 to dir2/dir1. mv 

creates any directories that it needs. 


DIAGNOSTICS 


0 

1 



— argument had trailing slash (/) but was not a directory 

— file could not be found 

— input file could not be opened for reading 

— output file could not be created or opened for output 

— read error occurred on an input file 

— write error occurred on an output file 

439 of 457

2 

— input and output files were the same file 

— input file could not be unlinked 

— input file could not be renamed 

— fatal error was encountered when using the -r option 

Possible fatal -r errors include the following: 

— inability to access a file 

— inability to read a directory 

— inability to remove a directory 

— inability to create a directory 

— a target that is not a directory 

— the source and destination directories are the same 




— a target that should be a directory but is not 

— no space left on the target device 


— the inability to create a directory to hold a target file 

cannot allocate target string 

mv has no space to hold the name of the target file. Try to free up some memory to give mv 

more space. 

filename read only? 

You are attempting to move a file, but there is already a file with the target name and the file 

is read-only. If you really want to write over the existing file, type y and press ENTER. If you 

do not want to write over the existing file, type n and press ENTER. 

source "name" and target "name" are identical 

The source and the target are actually the same file (for example, because of links on UNIX 

and POSIX-compliant systems). In this case, mv does nothing. 

unreadable directory "name" 

mv cannot read the specified directory (for example, because you do not have appropriate 

permissions). 

PORTABILITY 



440 of 457

The -d, -r, and -v options are extensions to the POSIX standard. The -d and -s options are only 

available on Windows. 

AVAILABILITY 











SEE ALSO 

Commands: 

cp, ln, pending, rm 

441 of 457

NAME 

nm 

nm — display symbol table of object, library, or executable file 

SYNOPSIS 

nm [-AaefgnoPprsuvx] [-t format] file ... 

DESCRIPTION 

nm displays the symbol table associated with an object, archive library of objects, or executable file. 

nm recognizes several different file types that may contain symbol tables: 

● object files ending in .obj. These files may be Intel OMF (Object Module Format) files or 

COFF (Common Object File Format) files. 

● library files, which normally end in .lib and contain one or more OMF or COFF files. 

● Windows executable files, which normally end in .exe, that contain a symbol table 

compatible with those produced by PLINK86, the Microsoft Linker, the Watcom Linker, or 

the Borland Linker. 

● A symbol table may be created from a .map file (such as those produced by Microsoft 

link) by using unstrip to create a symbol table compatible with PLINK86. 

Note that nm does not list entry points in a DLL, unless there is a symbol table associated with it. 

By default, nm lists the symbols in file in alphabetical order by name and provides the following 

information on each: 

● File or object name (if you specified -A) 

● Symbol name 

● Symbol type: 

Note: 

A 

a 

Not all of these symbol types are available on all systems. For instance, not all 

systems support the ability to determine different segment information. 

absolute symbol, global 

442 of 457

B 

b 

D 

d 

F 

l 

N 

n 

S 

s 

T 

t 

U 

? 

absolute symbol, local 

uninitialized data (bss), global 

uninitialized data (bss), local 

initialized data, global 

initialized data, local 

file name 

line number entry (see -a option) 

no defined type, global; this is an unspecified type, compared to the undefined type U 

no defined type, local; this is an unspecified type, compared to the undefined type U 

section symbol, global 

section symbol, local 

text symbol, global 

text symbol, local (static) 

undefined symbol 

443 of 457

● Symbol value 

unknown symbol 

● Symbol size, if applicable 

Options 

-A 

-a 

-e 

-f 

-g 

-n 

-o 

-P 

prefixes each line with the file name or archive member name. 

displays all symbols, including line number entries on systems which support them. 

displays only global (external) and static symbols. 

displays full output. This is the default, since this implementation does not suppress any 

output. 

displays only global symbols. 

is equivalent to -v. 

displays output in octal (same as -t o). 

displays output in a portable POSIX-compliant format, with blanks separating the output 

fields. If you specified -A and file is not a library, the format is 

file: name type value size 

If you specified -A and file is a library, the format is 

file[object_file]: name type value size 

where object_file is the object file in the library which contains the symbol being described. If you 

did not specify -A, the format is 

444 of 457

name type value size 

If you did not also specify the -t option, nm displays value and size in hexadecimal. 

If you did not specify -A and the command line contains more than one file, or file is a library, nm 

displays a line preceding the list of symbols for each specified file or each object file in a specified 

library. If file is a library, this line has the following format: 

file[object_file]: 

If file is not a library, the format is simply 

-p 

-r 

-s 

file: 

does not sort output. 

reverses sort order. 

includes symbol size for each symbol. 

-t format 

defines the numeric value formatting base. The format shall be one of d, o, or x, for decimal, 

octal, or hexadecimal, respectively. If this option is not used, numbers are displayed in 

decimal. 

-u 

-v 

-x 

displays only undefined symbols. 

sorts output by value. 

displays information in hexadecimal (same as -t x). 

DIAGNOSTICS 


0 

445 of 457

1 




— missing file name 

— unknown symbol table type 

— invalid library file 

— end-of-file found in library 

— bad record in the library 

— out of memory 

If a file does not contain a symbol table, nm displays a warning and goes to the next file, but this is 

not considered an error. 

PORTABILITY 



The -a, -e, -f, -n, -o, -p, -r, -s and -x options are not part of the POSIX standard. 

The -a, -n, -p, -r, -s options and -t d are not part of the x/OPEN standard. 

NOTE 

On Windows systems, data (D, d) and uninitialized data (B, b) are not currently recognized in 

executable files, as this involves trying to guess segment types. All such symbols come out as text 

(T, t) symbols. 

AVAILABILITY 








446 of 457

SEE ALSO 

Commands: 

ar, size, strip 

447 of 457

NAME 

rm — remove files 

SYNOPSIS 

rm [-fiRrv] [-d|s] file ... 

DESCRIPTION 

rm -- Command, KornShell Built-in 

rm removes each specified file argument (provided that it is a valid path name). If you specify 

either . or .. as the final component of the path name for a file, rm displays an error message, 

and moves onto the next file. If you specify a file you do not have write permission for, rm asks you 

for confirmation. Type the yes expression defined in LC_MESSAGES (the English expression is 

typically y or yes) if you really want it deleted. 

Options 

-d 

-f 

-i 

-R 

delays the removal of the specified files until the system is rebooted. This option and the -s 

option are mutually exclusive. 

This option relies upon the underlying operating system's capability to perform the action at 

reboot time. 

deletes read-only files immediately, without asking for confirmation. When you specify this 

option and a file does not exist, rm does not display an error message and does not modify 

the exit status. If you specify both -f and -i, rm uses the option that appears last on the 

command line. 

prompts for confirmation (from standard input) before deleting each file or confirmation 

before entering a subdirectory if either the -r or -R option is specified. If you specify both 

-f and -i, rm uses the option that appears last on the command line. 

recursively removes the entire directory structure if file is a directory. 

448 of 457

-r 

-s 

-v 

is equivalent to -R. 

saves the file for undeletion if possible. An attempt is made to put the file in the Recycle Bin 

and if this attempt fails then the file is quietly deleted. This option and the -d option are 

mutually exclusive. 


DIAGNOSTICS 


0 

1 

2 

NOTE 



— inability to remove a file 

— tried to remove directory without specifying -r or -R 

— inability to find file information when using -r or -R 

— inability to read directory when using -r or -R 



— no files specified 

rm is provided as both an external utility and a built-in MKS KornShell utility. 

PORTABILITY 



The -d, -s, and -v options are extensions to the POSIX standard. The -d and -s options are only 

449 of 457

available on Windows. 

AVAILABILITY 











SEE ALSO 

Commands: 

cp, mv, pending, rmdir, sh 

450 of 457

NAME 

touch — change file modification date 

SYNOPSIS 

touch 

touch [-acm] [-f agefile] [-r agefile] [[-t] time] file ... 

touch [-acm] time file ... 

DESCRIPTION 

The touch command changes certain dates for each file argument. By default, touch sets both 

the date of last file modification and the date of last file access to the current time. This is useful for 

maintaining correct release times for software and is particularly useful in conjunction with the MKS 

Make software development facility. 

Options 

-a 

-c 

-m 

sets only the access time. 

does not create any files that do not already exist. Normally, touch creates such files. 

sets only the modification time. 

If you do not specify -a or -m, touch behaves as though you specified both. 

To tell touch to use a time other than the current, use one of the following options: 

-f agefile 

is an obsolete version of the POSIX-compliant -r option. 

-r agefile 

sets the access and modification times (as indicated by the other options) to those kept for 

agefile. 

-t time 

specifies a particular time using this format: 

[[[[cc]yy]MM]dd]hhmm[.ss] 

451 of 457

where cc is the optional first 2 digits of the year, yy is the optional last 2 digits of the year, MM is 

the optional number of the month (01-12), dd is the optional day of the month, hh is the hour in 24 

hour format (required), mm is the minutes (required), ss is the optional seconds. 

An obsolete (but still supported) version of this command lets you omit the -t, but the format is: 

MMddhhmmyy[yy] 

EXAMPLES 

touch newfile 

sets the modification time of newfile to the present. 

touch -t 8001031305 oldfile 

sets the modification time of oldfile to 13:05 on January 3, 1980. 

touch -r oldfile newfile 

sets the modification time of newfile to that of oldfile. 


TZ 

contains the time zone that touch is to use when interpreting times. 

DIAGNOSTICS 


0 

1 



— inability to access the desired file 

— system cannot support such an early date 

452 of 457

2 

Messages 

— inability to create a file 

— inability to change a file's times 

Failure that resulted in a usage message, including: 

— unknown command line option 

— only one of -t, -f, or -r is allowed 

— -r was missing the agefile 

— -t was missing its argument 

— invalid date string (bad date conversion) 

Age file inaccessible 

indicates that time could not be found for the file given with the -f or -r option either 

because that file does not exist or because the requesting user is not granted the 

appropriate permission for the file. 

Missing age file argument 

You specified -f or -r, but did not give a file name after it. 

Years earlier than year invalid 

Your system only recognizes dates back to the given year. touch does not accept dates 

before that time. 

Bad date conversion 

Only one -r(-f) or -t flag allowed 

Missing date/time argument 

Self-explanatory. 

PORTABILITY 



NOTE 

touch is provided as both an external utility and a built-in MKS KornShell utility. 

On the extended FAT file system, the earliest date accepted is 1980. On the NTFS file system, the 

earliest date accepted is 1970. 

The touch utility does not accept dates and times past 11:59.59 pm on December 31, 2099. 

453 of 457

AVAILABILITY 











SEE ALSO 

Commands: 

cp, date, sh 

454 of 457

NAME 

which, whereis 

which, whereis — display full path name for executable command 

SYNOPSIS 

which [-a] command ... 

whereis command ... 

DESCRIPTION 

Windows systems use the PATH environment variable to determine which directories are searched 

to find programs. If PATH is not found under Windows NT/2000/XP/2003, which then searches for 

Path. For each command, which looks through the directories in the search path, and displays the 

name of the first executable file that matches command. 

which uses the PATHEXT environment variable to determine which files are considered 

executable. As which searches each directory in the search path, it appends each of the 

extensions in the list, in turn, to command name to see if it matches a file name in that directory. If 

a match exists, that file is considered to be executable. 

If PATHEXT is not defined, which only considers files with a .exe, .com, .bat, or .cmd 

extension to be executable. 

Because which is intended primarily for use when working from the Windows command prompt, it 

always searches the current directory first before consulting the search path in the same way that 

Windows command interpreters (such as command.com and cmd.exe) do. 

Note: 

When running which from the Windows command prompt, not all executable files reported 

may be directly executable from the prompt. Such files may require the use of an additional 

program (such as a shell) to execute it. The program to use can normally be determined by 

the file's extension. For example, files with a .sh extension should be executed using the 

MKS KornShell. 

The whereis command is equivalent to specifying which -a. 

Options 

455 of 457

-a 

displays all matching executable files from every directory in PATH (on Windows Me) or in 

Path (on Windows NT/2000/XP/2003), not just the first match. This can help you find 

conflicts between two executables of the same name. 


PATH 

contains a list of directories for which to search when looking for command. 

PATHEXT 

contains a list of file extensions (separated by semicolons) for executable commands. By 

default, PATHEXT, has the value of Windows NT/2000/XP/2003's PATHEXT variable with 

.com;.exe;.bat;.sh;.ksh;.csh;.sed;.awk;.pl appended (omitting any 

extensions already represented in PATHEXT). 

DIAGNOSTICS 


0 

1 

An appropriate executable file can be found with the current PATH. 


PORTABILITY 

— an appropriate executable file cannot be found 


Available on some UNIX systems. Windows Me. Windows NT 4.0. Windows 2000. Windows XP. 

Windows Server 2003. 

NOTE 

This command does not know about shell keywords, aliases, functions, and so forth. For this 

reason, whence is recommended when you are using the MKS KornShell. 

456 of 457

AVAILABILITY 











SEE ALSO 

Commands: 

command, sh, whence 

457 of 457

Description - Mks.com

You also want an ePaper? Increase the reach of your titles

Delete template?

Save as template?