Set Up hrefresh

cahscm101
The hrefresh utility setup requires the following administrative tasks:
  1. Configure the server, client, and agent.
  2. Define the hrefresh Configuration File.
  3. Define the hrefresh Argument File.
  4. Create the Encrypted Password Files.
  5. Define
    CA Harvest SCM
    UDPs for hrefresh.
Define the hrefresh Configuration File
Create and define a configuration file, by default named HRefresh.cfg. The hrefresh configuration file is an ANSI text file that contains reference definition records. Each reference definition is a comma-delimited set of items on a single line.
The order of items and permissible values for a reference definition are as follows:
  1. Project
  2. State
  3. Check-out process name (The process must have Browse and Synchronize modes enabled.)
  4. View path
  5. Remote agent host path
  6. Reference directory type [“Full | Active”] (case-independent)
  7. Remote agent computer name or IP address
  8. Remote agent port number
  9. File name containing the username/password of
    CA Harvest SCM
    user (for -eh)
  10. File name containing the username/password of Agent user (for -er)
  11. (Optional) Purge options and purge exclusion lists.
  12. (Optional) Pre-check-out command definitions
  13. (Optional) Post-check-out command definitions
The pre- and post- check-out command definitions let you specify lists of commands to run before and after hsync executes. Hexecp executes the commands using the same authentication (-er file) as hsync. You can configure multiple pre and post commands to run using the syntax PreCmds: {command 1; command 2;…} and PostCmds: {command 1; command 2;…}. hrefresh executes each command asynchronously in the order listed (command 1 executes first, then command 2, and so on).
The pre and post commands have the following format:
PreCmds: {command 1; command 2;…}, PostCmds: {command 1; command 2;…}
The following rules apply to PreCmds and PostCmds:
  • Enclose all pre and post commands with parentheses separated by a semicolon “;”.
  • Separate pre and post commands with commas “,”.
  • Each command can include a program to execute followed by a list of arguments.
  • Specify the program to execute as a fully qualified path with no spaces.
  • Separate each passed argument with a space.
Example: Format PreCmd and PostCmd
CA World 2007, Development , Check Out for Browse , \Web Application\WebDev\B2CApp,c:\build\dev, Full, hasqlwin2k3, 7001, myuser.dfo,agentadmin.dfo,PreCmds: {C:\Perl\bin\perl.exe C:\temp\rcommand\rcmd.pl I am First "Pre Command"; C:\Perl\bin\perl.exe C:\temp\rcommand\rcmd.pl "I am Second" "Pre Command"}, PostCmds: {C:\Perl\bin\perl.exe C:\temp\rcommand\rcmd.pl "I am First" "Post Command"; C:\Perl\bin\perl.exe C:\temp\rcommand\rcmd.pl I am Second Post Command}
To define your reference directories, do the following:
  1. Create an ANSI text file and specify a name for the hrefresh configuration. The default name is HRefresh.cfg.
  2. Enter items and permissible values in the order as described earlier in this section.
    • Blank lines are allowed but hrefresh ignore them.
    • Comment lines are allowed, and are designated by “#” or “//” at the beginning of the line.
  3. Save and close the file.
  4. Place the file in the hrefresh home directory that is defined in the HRefresh.arg file. If the home directory is not defined, place the file in CA_SCM_HOME.
Following is a sample configuration file:
projA,TEST, , \Rep\Src,c:\build\test,Active,winmach,7001,hartest.dfo,winmach.dfo
projA,TEST, , \Rep\Src,/build/test,Active,lnxmach,7001,hartest.dfo,lnxmach.dfo
projA,TEST, , \Rep\Src,/build/test,Active,aixmach,7001,hartest.dfo,aixmach.dfo
projA,TEST, , \Rep\Src,/build/test,Active,hpmach,7001,hartest.dfo,hpmach.dfo
projA,DEV, , \Rep\Src,c:\build\dev,Active,winmach,7001,hardev.dfo,winmach.dfo
projA,DEV, , \Rep\Src,/build/dev,Active,lnxmach,7001,hardev.dfo,lnxmach.dfo
projA,DEV, , \Rep\Src,/build/dev,Active,aixmach,7001,hardev.dfo,aixmach.dfo
projA,DEV, , \Rep\Src,/build/dev,Active,hpmach,7001,hardev.dfo,hpmach.dfo
projA,RELEASE, , \Rep\Src,c:\build\rel,Full,winmach,7001,harrel.dfo,winmach.dfo
projA,RELEASE, , \Rep\Src,/build/rel,Full,lnxmach,7001,harrel.dfo,lnxmach.dfo
projA,RELEASE, , \Rep\Src,/build/rel,Full,aixmach,7001,harrel.dfo,aixmach.dfo
projA,RELEASE, , \Rep\Src,/build/rel,Full,hpmach,7001,harrel.dfo,hpmach.dfo
hrefresh Argument File Definition
This task is optional.
The hrefresh argument file defines the following:
  • Maximum Retry Value
  • Retry Delay Value in seconds
  • -nolock option
  • hrefresh home directories for each broker name
    The home directory locates the hrefresh configuration file and the encrypted password files. In each hrefresh home directory, create a subdirectory named log for the hrefresh log files.
  • (Optional) Configuration file name. Default is HRefresh.cfg.
  • (Optional) Execute mode; synchronous or asynchronous (default).
The HRefresh.arg file is optional but recommended. If you omit the HRefresh.arg file, the hrefresh home directory is
CA_SCM_HOME
and no retry capability is enabled.
HRefresh.arg supports the following arguments:
  • -maxretries=
    n
    Specifies the maximum number of job retries. If hrefresh determines that an hrefresh job is running for a particular host, hrefresh waits and retries the job up to
    n
    times. If you do not specify this parameter, the default is 0 (do not retry).
  • -retrydelay=
    n
    Sets the number of seconds to wait between retry attempts, if you configure hrefresh to retry a job when a previous job is still running (maxretries>0). If you do not specify this parameter, the default is 0 (no delay between retries).
  • -nolock
    Overrides semaphore locks and allows multiple check-out operations for the same target directory to run concurrently. If you do not specify -nolock, the semaphore locks are active (the default), and the check-out operations run consecutively. Use -nolock with caution.
    When -nolock is in effect, the -maxretries and -retrydelay settings in the HRefresh.arg file are ignored.
  • -home=
    directory
    Sets a default directory that hrefresh uses as the home directory. If you do not specify this parameter, hrefresh uses CA_SCM_HOME.
  • -home_
    name
    =
    directory
    Sets a default directory that hrefresh uses as the home directory in cases where multiple brokers or hserver version groups exist on a single
    CA Harvest SCM
    server installation. If you do not specify this parameter for a broker name or version name, the value specified by
    -home=directory
    is used.
    This option mimics the -homeserver_
    version
    argument in HBroker.arg, in which you specify where to find the HServer.arg file for each hserver version.
For example, if your HBroker.arg file specifies the following:
//Version 1 for Telon Group
-minserver_telon=10
-maxserver_telon=35
-queuesize=5
-homeserver_telon=H:\CA\Software Change Manager\Ver1
//Version 2 for Telco Group
-minserver_telco=2
-maxserver_telco=35
-queuesize=5
-homeserver_telco=H:\CA\Software Change Manager\Ver2
You create separate hrefresh home directories for each group in HRefresh.arg as follows:
//Version 1 for Telon Group
-home_telon=H:\CA\Software Change Manager\Ver1
//Version 2 for Telco Group
-home_telco=H:\CA\Software Change Manager\Ver2
The
name
portion of the argument is matched at runtime using the following logic:
  1. If the broker value is in the form
    brokername
    /
    version
    ,
    version
    locates a designated hrefresh home directory.
  2. If the broker value does not have the version name,
    brokername
    locates a designated hrefresh home directory.
  3. If no match exists for either one, the -home value is used when it is defined; otherwise, CA_SCM_HOME is used.
This approach supports cases where
brokername
is forced using RT_FORCE_NODE_NAME, and where multiple brokers may be running.
  • -cfg=filename
    (Optional) Specifies the configuration file name.
    Default:
    HRefresh.cfg
  • execmode= synchronous|asynchronous
    (Optional) Sets the default execution mode for all hrefresh executions, unless overridden by using -execmode on the hrefresh command line.
    Default:
    asynchronous
To define the argument file, do the following:
  1. Create an ANSI text file and name the file HRefresh.arg.
  2. Place the file in the CA_SCM_HOME directory.
  3. Enter arguments and permissible values in the order as described earlier in this section.
    Blank lines are allowed, but hrefresh ignores them.
    Comment lines are allowed, and are designated by “#” or “//” at the beginning of the line.
  4. Save the file and make sure it remains in the CA_SCM_HOME directory.
Semaphore Locks
CA Harvest SCM
uses semaphore locks to help prevent failures that may occur when multiple check-out operations for the same target directory are run concurrently. For example, a configuration post-links hrefresh to the check-in process. Each time a user checks in versions, hrefresh automatically synchronizes one or more corresponding reference directories. When another check-in occurs in the same state before the first hrefresh job is finished, a semaphore file created by the first job blocks the second hrefresh job. The second job waits for a specified period (set by the -retrydelay=
n
parameter) for the first job to finish. The second job aborts if the semaphore file is not released within the specified period.
The semaphore-lock files that hrefresh creates are named
project_state_host
.lock and are stored in the directory that you specify as your hrefresh home directory. These lock files are not deleted when jobs complete. An active job obtains an exclusive lock on the semaphore file when it starts, and releases that lock when it finishes.
In some cases, you may want to change this locking behavior; for example, when you want to synchronize multiple separate directories on a single host. The hrefresh configuration file may contain the following entries:
#Project ,  State ,, Viewpath   , Clientpath, Type, Host , ...
Project 1, State 1,, \Rep1\path1, /dir1     , Full, host1, ...
Project 1, State 1,, \Rep1\path2, /dir2     , Full, host1, ...
Project 1, State 1,, \Rep1\path3, /dir3     , Full, host1, ...
In this example, by default, hrefresh does
not
allow the check-outs for these three directories to execute concurrently. Instead, the processes run consecutively. The job for /dir1 starts, and the other jobs wait until that job is finished.
For some users, the semaphore locks that require processes to run consecutively are more time-consuming than necessary. To override semaphore locks and allow the jobs to run concurrently, specify the -nolock option, as follows:
  • To set -nolock for all hrefresh executions, add a line specifying -nolock to your HRefresh.arg file.
  • To set -nolock for certain instances of hrefresh, specify -nolock as a command-line option when hrefresh is invoked. You can specify the -nolock option on the program line in hrefresh UDP definitions or custom scripts.
For details about hrefresh command-line options, see the
Reference section
.
Encrypted Password Files
Each reference definition in the configuration file requires two sets of user names and passwords.
  • CA Harvest SCM
    login uses one set for running the check-out using hsync.
  • hsync and hexecp use one set for the remote agent connection.
CA Harvest SCM
encrypted password files, created by svrenc -f, provide the user names and passwords. As an administrator, you run svrenc -f
filename
for each unique username and password. You name the password files and use these names in the configuration file.
Reference definitions can share password files. All hsync operations in a single system can use a single
CA Harvest SCM
user account. Remote agent login user names and passwords can also be shared.
hrefresh UDP Definitions
The
CA Harvest SCM
administrator determines how hrefresh is used in each lifecycle. The flexibility of this command enables various levels of hrefresh automation.
In a simple case, you can define stand-alone UDPs for the on-demand execution of hrefresh. Such UDPs may also be used to initially populate reference directories when more automated mechanisms are being used. For stand-alone hrefresh UDPs, the function synchronizes to all related reference directories all items in the context of the view path (as configured in the reference definition).
hrefresh can be invoked automatically when
CA Harvest SCM
packages are promoted and demoted. This refreshes only those items contained in the list of packages being promoted or demoted.
Whether the UDP is stand-alone or linked, the basic definition is as follows:
  • Program
    hrefresh -b "[broker]" -pr "[project]" -st "[state]" -nst "[nextstate]"
  • Input
    [package]
    [version]
A sample definition of an hrefresh UDP follows:
Shows a sample definition of an hrefresh UDP.
Video Icon.PNGVideo Tutorial: 
See the how to video tutorial for using the hrefresh capability:
  • Using Hrefresh Capability

  • Hrefresh Using Promote Process