hco Command-Check-out

The hco command executes the check-out process specified on the command line or the first check-out process in the current context if no process name is specified. The process definition determines the default behavior for the Replace Read-Only Files option, process access, and execution of linked processes. Other aspects of the process can be specified through command parameters read from the command line.
cahscm101
The hco command executes the check-out process specified on the command line or the first check-out process in the current context if no process name is specified. The process definition determines the default behavior for the Replace Read-Only Files option, process access, and execution of linked processes. Other aspects of the process can be specified through command parameters read from the command line.
The options -up, -br, -ro, -sy, and -cu are for Update, Browse, Reserve Only, Synchronize, and Concurrent Update, respectively.
This command has the following format:
hco 
filename(s)
 | 
pattern
 {-b 
name
 -en 
name
 -st 
name
 -vp 
path
 -p 
name
}{-up | -br | -ro | -sy | -cu} {-usr 
username
 -pw 
password
} [-vn] [-nvs] [-nvf] [-r] [-replace 
option
] [-v] [-nt] [-ss 
name
] [-s
 filename
 | 
pattern
] [-pf 
name
 [-po]]  [-bo -to -tb] [-ced] [-dvp 
path
] [-dcp 
path
] [-cp
 path
] [-op
 option
] [-pn 
name
] [-rm 
name -
rport
 portnumber
] [-rusr 
username
] [-rpw 
password
] [-prompt] [-i
 inputfile.txt
 | -di 
inputfile.txt
] [-eh 
filename
] [-er 
filename
] [-o
 filename
 | -oa
 filename
] [-arg] [-wts] [-tr] [-h]
  • filename(s)
     | 
    pattern
    Specifies file name(s) or naming pattern used for check-out.
  • -b 
    name
    (Required) Specifies the 
    CA Harvest SCM
     broker name.
  • -en 
    name
    (Required) Specifies the 
    CA Harvest SCM
     project context. If the project name contains spaces, enclose the name in quotation marks.
  • -st 
    name
    (Required) Specifies the name of the state in which the user is operating.
  • -vp 
    path
    (Required) Specifies the 
    CA Harvest SCM
     view path that corresponds to the current working directory.
  • -p 
    name
    (Required, unless -br or -sy is specified.) Specifies the package context to be used for update, concurrent update, and reserve only modes, read from the command line or a signature file.
    Note:
     Package context is ignored for check-out for browse and synchronize.
  • -up
    (Required: -up, -br, and -ro are mutually exclusive and one is required.) Specifies that the items should be copied to the destination directory and a reserved version for each created, allowing the files to be checked back in. Only the latest trunk version of an item, or the latest version on an unmerged branch, can be checked out for Update.
  • -br
    (Required: -up, -br, -ro, -sy, and -cu are mutually exclusive and one is required.) Specifies that the items should be copied to the destination directory but does not allow you to check the files back in. The file permission is set to read-only. If no version number (-vn) or branch only (-bo) options are specified, Browse mode selects the latest trunk version.
  • -ro
    (Required: -up, -br, -ro, -sy, and -cu are mutually exclusive and one is required.) Specifies that no data is to be moved to external directories, but the items are marked as reserved so they can be checked back in.
  • -sy
    (Required: -up, -br, -ro, -sy, and -cu are mutually exclusive and one is required.) Specifies synchronize mode, which identifies the versions of the files in the client file system by using the signature file. 
    CA Harvest SCM
     versions are checked out only if the signature file shows the following differences:
    • Client files that differ from their corresponding 
      CA Harvest SCM
       versions.
    • Client files whose timestamps differ from their corresponding timestamps in the signature file.
    • Items are checked out in read-only mode. The check out for synchronize mode is especially useful in the build process.
      For more information on signature files, see the
      Using section
      .
  • -cu
    (Required: -up, -br, -ro, -sy, and -cu are mutually exclusive and one is required.) Specifies that the items be copied to the destination directory and a reserved version created for each, allowing the files to be checked back in. Unlike Update, Concurrent Update creates the reserved version on a branch of the trunk. The permission on a read-only file is changed to normal (writable) when this mode of check-out is used.
  • -usr 
    username
    (Required, unless -prompt is specified) Defines the user name for login to the broker. If -usr is defined without -pw, the user is prompted for the password at runtime.
  • -pw 
    password
    (Required, unless -prompt is specified) Defines the password for login to the broker. To hide the password from being exposed in plain text on the command line, use the -prompt option.
  • -vn
    (Optional) Specifies a version of an item for browse or concurrent update. If no version is specified with the -vn option, the latest version of the item in the view associated with the specified state is checked out.
    Occasionally, this algorithm can lead to errors. If, for example, you are trying to check out an item for update and later versions exist in another view, hco will generate an error. To check out such an item, you must use the Concurrent Update mode.
    Specifying more than one -vn parameter on the command line check-out is not allowed. After a version is specified with the -vn option, that version is used for all files checked out.
    The -vn option cannot be used with the Synchronize (-sy) or Update (-up) modes of check-out or update.
  • -nvs
    (Optional) Specifies that latest, normal, and trunk versions are recursively selected for check-out.
    When -nvs is used, the [version] system variable will not be populated in processes linked to the check-out process.
    This option is intended to decrease the memory requirements for checking out a large amount of versions.
    The -nvs option cannot be used with options: -po, -pf, -bo, -vn, -s, -tb, or -dvp.
  • -nvf
    (Optional) Specifies how 
    CA Harvest SCM
     handles “file not found” errors that occur when the hco command is running.
    When you specify - nvf, if one or more specified items is missing or if no search results found, 
    CA Harvest SCM
     does the following actions:
    • Aborts the check out
    • Displays an error message
    • Returns error code 14
    When you do not specify - nvf, if one of the conditions occurs, then 
    CA Harvest SCM
     continues the check out, displays a warning message, and returns a “successful” code.
  • -r
    (Optional) Specifies whether the checked-out files should replace existing read-only files on the host. When -r is specified, existing read-only files are replaced. This lets you replace files that you previously checked out for Browse, or checked in complete, without having to manually modify the file's access. If you do not specify the - r option, the check out does not replace any existing read-only files, regardless of the Administrator application setting.
    Files that exist with write permission are never overwritten. 
    CA Harvest SCM
     assumes that such a file has been checked out for Update and not checked back in yet. Overwriting such a file might cause a user to lose unsaved changes.
    If no corresponding file exists, the item is checked out regardless of whether the -r option is used.
    UNIX and Linux:
     The Replace Read-Only Files option replaces files only if the user who is executing the check-out process owns them.
  • -replace
    (Optional) Specifies if existing files are to be replaced during check-out. Specify one of the following options:
    • ro
      Replaces read-only files only.
    • rw
      Replaces writable (read/write) files only.
    • all
      Replaces both read-only and writable files.
    -replace and -r are mutually exclusive.
  • -nt
    (Optional) Specifies versions with normal tag.
  • -ss 
    name
    (Optional) Specifies the name of the snapshot view. If used in the check-out process, the state specified must have All Snapshot Views enabled.
  • -s 
    filename
     | 
    pattern
    (Optional) Specifies that the check-out process should search every directory below the current one for files that match a file name or naming pattern. This option must be followed by a file name or naming pattern. To specify multiple file names or naming patterns, use the -s option before the first file name or pattern. -s will search for the patterns specified between it and the next option. 
    Naming patterns that include a wildcard must be enclosed in single or double quotes when used with the -s option. If no quotes are included on multiple naming patterns, hco searches recursively for the first file (the naming pattern immediately following the -s option) and searches only the current directory for the remaining files.
Examples: -s option
To recursively check out all files with the .c file extension, use the following command:
hco [
options
] -s "*.c"
To check out *.c and *.exe and recursively check out the files one.c, two.c, and three.c, use the following command:
hco file.txt *.c ... -s one.c two.c three.c [
option
] *.exe
  • -pf
    (Optional) Specifies that items should be selected based on package contents. Checks out the latest versions from the current view of all items that have any version associated with the specified package. If used with the -po option, checks out the latest versions associated with the -pf specified package. Specifying more than one -pf parameter is not allowed.
  • -po
    (Optional) Specifies that the latest version should be checked out from the list of packages passed in by the -pf option. -po is a sub-option of -pf and cannot be used by itself.
  • -bo
    (Optional) Specifies to check out only versions located on branches. If you specify a trunk version using the -vn option and also specify -bo, no version will be selected.
  • -to
    (Optional) Specifies to check out only versions located on the trunk. This is the default. If you specify a branch version using the -vn option and also specify -to, no version will be selected.
  • -tb
    (Optional) Specifies to check out versions located on the trunk and branches.
  • -ced
    (Optional) Enables the creation of directories that contain no items during a recursive check-out. The default is to create no empty directories.
  • -dvp 
    path
    (Optional) Specifies a default view path.
  • -dcp 
    path
    (Optional) Specifies a default client path.
  • -cp 
    path
    (Optional) Specifies the client path that corresponds to current view path. The client path must be an absolute path.
  • -op 
    option
    (Optional) Specifies where files or items should be placed in relationship to the specified view path or client directory structure. Specify one of the following options:
    • p
      Preserve directory structure
      -Checks out all selected items into corresponding client directories, if they already exist. If the directories do not exist, an error message is displayed and the items are not checked out.
    • pc
      Preserve and create path structure
      -Checks out selected files to paths with names that correspond to their client directory location, and creates any view paths that do not currently exist.
    • as
      All files to same view path
      -Checks out all selected files to the same path in the destination view, ignoring the client directory structure.
  • -pn 
    name
    (Optional) Specifies a specific process name to invoke if more than one process of the same type exists in the state. If no process name is included in the command, the first process of that type for which the user has execute access and that allows the specified mode in the specified state is invoked.
  • -rm 
    name
    (Optional) Specifies the remote computer to check out from or check in to. Specify this option only if you want to check out from or check in to a remote computer.
  • -rport 
    portnumber
    (Optional) Specifies the port number of the remote computer to check out from or check in to. Specify this option only if you want to check out from or check in to a remote computer.
  • -rusr 
    username
    (Optional) Specifies the username for the remote computer to check out from or check in to. Specify this option only if you want to check out from or check in to a remote computer.
  • -rpw 
    password
    (Optional) Specifies the password for the remote computer to check out from or check in to. Specify this option only if you want to check out from or check in to a remote computer.
  • -eh 
    filename
    (Optional) Specifies the encrypted 
    CA Harvest SCM
     username-password file name. The file name used with this option contains encrypted username-password credentials and must be generated with the svrenc utility.
  • -er
    (Optional) Specifies the encrypted remote username-password file name. The file name used with this option contains encrypted username-password credentials and must be generated with the svrenc utility. -er overrides -rusr and -rpw options.
  • -tr
    (Optional) Turns on the local agent network activity trace.