Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Newer
Older
100644 317 lines (234 sloc) 8.333 kB
f9ec5a5 @mithun CPAN Release 0.06
authored
1 # NAME
2
3 CASCM::Wrapper - Run CA-SCM (Harvest) commands
4
5 use CASCM::Wrapper;
6
7 # Initialize
8 my $cascm = CASCM::Wrapper->new();
9
10 # Set Context
11 $cascm->set_context(
12 { # Set a global context. This is applied to all commands where required
13 global => { b => 'harvest',
14 eh => 'user.dfo',
15 },
16
17 # Set 'hco' specific context, applied only to hco commands
18 hco => { up => 1,
19 vp => '\repository\myapp\src',
20 pn => 'Checkout Items',
21 },
22
23 # Similarly for 'hci'
24 hci => { vp => '\repository\myapp\src',
25 pn => 'Checkin Items',
26 de => 'Shiny new feature',
27 },
28
29 # And 'hcp'
30 hcp => { st => 'development',
31 at => 'userid',
32 },
33 }
34 ) or die $cascm->errstr;
35
36 # Create Package
37 my $pkg = 'new_package';
38 $cascm->hcp($pkg) or die $cascm->errstr;
39
40 # Checkout files
41 my @files = qw(foo.c bar.c);
42 $cascm->hco( { p => $pkg }, @files ) or die $cascm->errstr;
43
44 # Update Context
45 $cascm->update_context( { hci => { p => $pkg }, } ) or die $cascm->errstr;
46
47 # Checkin files
48 $cascm->hci(@files) or die $cascm->errstr;
49
50 # DESCRIPTION
51
ad682f3 @mithun CPAN Release 0.07
authored
52 This module is a wrapper around CA Software Change Manager's (formerly known as Harvest) commands. It
f9ec5a5 @mithun CPAN Release 0.06
authored
53 provides a perl-ish interface to setting the context in which each command is
54 executed, along with optional loading of context from files as well as parsing
55 output logs.
56
57 # CONTEXT
58
59 The context is a _hash of hashes_ which contain the following types of keys:
60
61 - global
62
63 This specifies the global context. Any context set here will be applied to
64 every command that uses it.
65
66 my $global_context = {
67 global => { b => 'harvest',
68 eh => 'user.dfo',
69 },
70 };
71
72 - command specific
73
74 This provides a command specific context. Context set here will be applied only
75 to those specific commands.
76
77 my $hco_context = {
78 hco => { up => 1,
79 vp => '\repository\myapp\src',
80 pn => 'Checkout Items',
81 },
82 };
83
84 The global and command context keys are synonymous with the command line
85 options detailed in the CA-SCM Reference Manual. Options that do not require a
86 value should be set to '1'. i.e. `{hco => {up => 1} }` is equivalent
87 to `hco -up`. The methods are intelligent enough to apply only the context
88 keys that are used by a command. For e.g. a global context of `vp` will not
89 apply to `hcp`.
90
91 The 'common' options _i_ and _di_ are not applicable and ignored for all
92 commands. See ["SECURITY"](#SECURITY)
93
94 The following methods are available to manage context
95
ad682f3 @mithun CPAN Release 0.07
authored
96 ## set\_context($context)
f9ec5a5 @mithun CPAN Release 0.06
authored
97
98 Sets the context. Old context is forgotten. The argument provided must be a
99 hash reference
100
ad682f3 @mithun CPAN Release 0.07
authored
101 ## update\_context($context)
f9ec5a5 @mithun CPAN Release 0.06
authored
102
103 Updates the current context. The argument provided must be a hash reference
104
ad682f3 @mithun CPAN Release 0.07
authored
105 ## load\_context($file)
f9ec5a5 @mithun CPAN Release 0.06
authored
106
107 This loads the context from an 'INI' file. The root parameters defines the
108 global context. Each sectional parameter defines the command specific context.
109 Old context is forgotten.
110
111 # Load context file at initialization. This will croak if it fails to read the context file
112 my $cascm = CASCM::Wrapper->new( { context_file => $file } );
113
114 # Alternatively
115 $cascm->load_context($file) or die $cascm->errstr;
116
117 This is a sample context file
118
119 # Sample context file
120
121 # Root parameters. These define the 'global' context
122 b = harvest
123 eh = user.dfo
124
125 # Sectional parameters. These define the 'command' context
126
127 [hco]
128 up = 1
129 vp = \repository\myapp\src
130
131 [hcp]
132 st = development
133
134 __NOTE:__ This method requires [Config::Tiny](http://search.cpan.org/perldoc?Config::Tiny) in order to read the context
135 file.
136
ad682f3 @mithun CPAN Release 0.07
authored
137 ## get\_context()
f9ec5a5 @mithun CPAN Release 0.06
authored
138
139 Returns a hash reference of current context
140
141 my $context = $cascm->get_context();
142 use Data::Dumper;
143 print Dumper($context);
144
145 # CA-SCM METHODS
146
147 Almost every 'h' command that uses a context is supported. The command names
148 are synonymous with the methods used to invoke them.
149
150 Every method accepts two optional arguments. The first is an hash reference
151 that overrides/appends to the context for that method. This allows setting a
152 context only for that specific method call. The second is an array of arguments
153 that is passed on to the 'h' command. Any arguments provided is passed using
154 the '-arg' option.
155
156 # No parameters. Everything required is already set in the context
157 $cascm->hdlp() or die $cascm->errstr;
158
159 # Array of arguments
160 $cascm->hci( @files ) or die $cascm->errstr;
161
162 # Override/Append to context
163 $cascm->hci( { p => 'new_package' }, @files ) or die $cascm->errstr;
164
165 The methods can be called in a 'dry run' mode. Where the method returns the
166 full command line, without executing anything. This can be useful for
167 debugging.
168
169 $cascm = CASCM::Wrapper->new( { dry_run => 1 } );
170 $cascm->set_context($context);
171 $cmd = $cascm->hsync();
172 print "Calling hsync() would have executed -> $cmd";
173
174 The following CA-SCM commands are available as methods
175
176 hap
177 har
178 hci
179 hco
180 hcp
181 hdp
182 hdv
183 hft
184 hlr
185 hlv
186 hpg
187 hpp
188 hri
189 hrt
190 hsv
191 hup
192 hcbl
193 hchu
194 hcpj
195 hdlp
196 hspp
197 hsql
198 hudp
199 hfatt
200 hsmtp
201 hsync
202 hccmrg
203 hdelss
204 hexecp
205 hmvitm
206 hmvpkg
207 hmvpth
208 hrnitm
209 hrnpth
210 haccess
211 hcrrlte
212 hexpenv
213 hgetusg
214 himpenv
215 hrmvpth
216 hsigget
217 hsigset
218 htakess
219 hucache
220 husrmgr
221 husrunlk
222 hchgtype
223 hcmpview
224 hcropmrg
225 hcrtpath
226 hdbgctrl
227 hpkgunlk
228 hppolget
229 hppolset
230 hrefresh
231 hrepedit
232 hrepmngr
233 hauthsync
234 hformsync
235
236
237
238 # SECURITY
239
240 This module uses the _di_ option for executing CA-SCM commands. This prevents
241 any passwords from being exposed while the command is running. The temporary
242 _di_ file is deleted irrespective if the outcome of the command.
243
244 # LOGGING
245
246 Since CA-SCM commands output only to log files, this module allows parsing and
247 logging of a command's output. [Log::Any](http://search.cpan.org/perldoc?Log::Any) is required to use this feature,
248 which in turn allows you to use any (supported) Logging mechanism. When using
249 this, any 'o' or 'oa' options specified in the context will be ignored. Your
250 scripts will need to load the appropriate [Log::Any::Adapter](http://search.cpan.org/perldoc?Log::Any::Adapter) to capture the
251 log statements. The CA-SCM log is parsed and the messages are logged either as
252 'INFO', 'WARN' or 'ERROR'.
253
254 # Using Log4perl
255
256 use CASCM::Wrapper;
257 use Log::Log4perl;
258 use Log::Any::Adapter;
259
260 Log::Log4perl->init('log4perl.conf');
261 Log::Any::Adapter->set('Log4perl');
262
263 # Get logger
264 my $log = Log::Log4perl->get_logger();
265
266 # Set parse_logs to true. This will croak if Log:Any is not found.
267 my $cascm = CASCM::Wrapper->new( { parse_logs => 1 } );
268
269 # Set Context
270 my $context = { ... };
271 $cascm->set_context($context);
272
273 # Calling the method automatically will parse the log output into the Log4perl object
274 # The output is also logged in the 'CASCM::Wrapper' category.
275
276 $cascm->hco(@files) or die $cascm->errstr;
277
278 # ERROR HANDLING
279
280 All methods return true on success and `undef` on failure. The error that most
281 likely caused the _last_ failure can be obtained by calling the `errstr`
282 method.
283
284 # DEPENDENCIES
285
286 CA-SCM r12 (or higher) client. Harvest 7.1 might work, but has not been tested.
287
288 The CA-SCM methods depends on the corresponding commands to be available in the
289 _PATH_
290
291 At least Perl 5.6.1 is required to run.
292
293 Optionally, [Config::Tiny](http://search.cpan.org/perldoc?Config::Tiny) is required to read context files
294
295 Optionally, [Log::Any](http://search.cpan.org/perldoc?Log::Any) and [Log::Any::Adapter](http://search.cpan.org/perldoc?Log::Any::Adapter) is required to parse CA-SCM
296 log files
297
ad682f3 @mithun CPAN Release 0.07
authored
298 # SEE ALSO
299
300 [CA Software Change Manager](#http://www.ca.com/us/products/detail/CA-Software-Change-Manager.aspx)
301
f9ec5a5 @mithun CPAN Release 0.06
authored
302 # BUGS AND LIMITATIONS
303
ad682f3 @mithun CPAN Release 0.07
authored
304 Please report any bugs or feature requests to `bug-cascm-wrapper@rt.cpan.org`,
305 or through the web interface at
f9ec5a5 @mithun CPAN Release 0.06
authored
306 [http://rt.cpan.org/Public/Dist/Display.html?Name=CASCM-Wrapper](http://rt.cpan.org/Public/Dist/Display.html?Name=CASCM-Wrapper)
307
308 # AUTHOR
309
310 Mithun Ayachit `mithun@cpan.org`
311
312 # LICENSE AND COPYRIGHT
313
314 Copyright (c) 2012, Mithun Ayachit. All rights reserved.
315
316 This module is free software; you can redistribute it and/or modify it under
317 the same terms as Perl itself. See [perlartistic](http://search.cpan.org/perldoc?perlartistic).
Something went wrong with that request. Please try again.