[p4perl] Using global options with P4Perl.

Thu Feb 23 13:32:13 PST 2006

> I would like to user the P4::Tagged method but the documentation off
> of the perforce website doesn't have it.  All I see is
$p4->SetProtocol(tag,'');
> Is that the same thing?

The documentation is there, but it's inside the P4.pm file as POD (Plain
Old Documentation).

For those who are new to Perl, POD stands for Plain Old Documents and is
a way of embedding Perl documentation in a Perl program. You use the
pod2* programs to extract this information:

$ pod2text P4.pm > P4.txt

Don't worry if you didn't know this stuff. I used Perl for almost a
decade before I discovered "POD". And, even now that I knew about POD, I
also searched Perforce website for documentation before it occurred to
me that it was located in the P4.pm file.

Here's the documentation from the POD:

P4::Tag()
=========
Deprecated in favour of P4::Tagged (same functionality). 

P4::Tagged()
============
Responses from commands that support tagged output will be returned in
the form of a hashref rather than plain text. Must be called prior to
calling P4::Connect. [Note from me: Tagged output is explained below]

P4::IsTagged()
==============
Returns true if Tagged mode is enabled on this client. 
a previous call to SetPort(), or from $ENV{P4PORT} or a P4CONFIG file.

P4::Run( cmd, [$arg...] )
=========================
Run a Perforce command returning the results. Since Perforce commands
can partially succeed and partially fail, you should check for errors
using P4::ErrorCount().
Results are returned as follows:

    An array of results in array context.
    undef in scalar context if result set is empty.
    A scalar result in scalar context if only one result exists.
    An array ref in scalar context if more than one result exists.
Through the magic of the AutoLoader, you can also treat the Perforce
commands as methods, so:

 $p4->Edit( "filename.txt );
is equivalent to

 $p4->Run( "edit", "filename.txt" );
Note that the format of the scalar or array results you get depends on
(a) whether you're using tagged (or form parsing) mode (b) the command
you've executed (c) the arguments you supplied and (d) your Perforce
server version.
In tagged or form parsing mode, ideally each result element will be a
hashref, but this is dependent on the command you ran and your server
version.
In non-tagged mode ( default ), the each result element will be a
string. In this case, also note that as the Perforce server sometimes
asks the client to write a blank line between result elements, some of
these result elements can be empty.
Mostly you will want to use form parsing (and hence tagged) mode. See
ParseForms().
Note that the return values of individual Perforce commands are not
documented because they may vary between server releases.
If you want to be correlate the results returned by the P4 interface
with those sent to the command line client try running your command with
RPC tracing enabled. For example:

 Tagged mode:           p4 -Ztag -vrpc=1 describe -s 4321
 Non-Tagged mode:       p4 -vrpc=1 describe -s 4321
Pay attention to the calls to client-FstatInfo(), client-OutputText(),
client-OutputData() and client-HandleError(). Each call to one of these
functions results in either a result element, or an error element.

-----Original Message-----
From: p4perl-bounces at perforce.com [mailto:p4perl-bounces at perforce.com]
On Behalf Of Rainey, Mark (Cleveland)
Sent: Thursday, February 23, 2006 11:48 AM
To: p4perl at perforce.com
Subject: Re: [p4perl] Using global options with P4Perl.

I would like to user the P4::Tagged method but the documentation off of
the perforce website doesn't have it.  All I see is
$p4->SetProtocol(tag,''); Is that the same thing?

Thanks,
Mark 

________________________________

From: p4perl-bounces at perforce.com [mailto:p4perl-bounces at perforce.com]
On Behalf Of Weintraub, David
Sent: Wednesday, February 15, 2006 12:13 PM
To: daniel.jacobs at symbian.com; p4perl at perforce.com
Subject: Re: [p4perl] Using global options with P4Perl.

P4Perl API isn't quite the same as running P4 from the command line. The
options are different and the output can be different.

However, take a look at the P4::Tagged method. This will put all of your
output into Tagged format. Tagged format is the same as using "-ztag"
global argument for the "p4" command (see "p4 help undoc") and can be
helpful when parsing output. Here's an example of the Tagged output for
the describe command vs.. the regular output:

	$ p4 describe -s 5519  #Normal Output
	Change 5519 by nbk55mm at nbk55mm-root-default
<mailto:nbk55mm at nbk55mm-root-default>  on 2006/02/15 11:21:05

	        Column width resize for the strike prices

	Affected files ...

	...
//depot/main/Components/MarketAnalyticsAndPricing/MarketMaker/OptionGrid
.cs#
82 edit
	...
//depot/main/Components/MarketAnalyticsAndPricing/MarketMaker/OptionGrid
.res
x#17 edit

	$ p4 -ztag describe -s 5519   #Tagged Output
	... change 5519
	... user nbk55mm
	... client nbk55mm-root-default
	... time 1140020465
	... desc Column width resize for the strike prices

	... status submitted
	... depotFile0
//depot/main/Components/MarketAnalyticsAndPricing/MarketMaker/OptionGrid
.cs
	... action0 edit
	... type0 ktext
	... rev0 82
	... depotFile1
//depot/main/Components/MarketAnalyticsAndPricing/MarketMaker/OptionGrid
.res
x
	... action1 edit
	... type1 ktext
	... rev1 17

As you can see, the tagged output puts the field name in front of every
line. This makes it much easier to parse your output.  If you combine
P4::Tagged with P4::ParseForms, each line becomes part of a Perl hash
which makes it even easier to work with these commands.

Remember you can always forgo the entire P4Perl API and simply embed P4
commands directly into your program. This is what I have to do because I
am unable to get the API installed on my Solaris Perforce server (it's a
long story). Below gives you an idea what I go through in order to do it
this
way:

	#
	#   ####Perl Modules
	#

	use Getopt::Long;       #Command Line Options Handling Module

	#
	#   ####Constants
	#

	*P4_PORT = \"localhost:1666";
	    our $P4_PORT;
	*P4_COMMAND = \"/local/bin/p4";
	    our $P4_COMMAND;
	*P4_USER = \"perforce";
	    our $P4_USER;

	#
	#   ####Get Command Line Parameters
	#

	my($p4Cmd, $p4User, $p4Password, $p4Port, $displayHelp);

	GetOptions (
	    "command=s"     => \$p4Cmd,
	    "user=s"        => \$p4User,
	    "password=s"    => \$p4Password,
	    "port=s"        => \$p4Port,
	    "help"          => \$displayHelp
	) or die "Invalid Command Line Parameters\n";

		#
	#   ####Set the parameters for the Perforce Command
	#

	$p4Cmd        = $P4_COMMAND    unless ($p4Cmd);
	$p4User       = $P4_USER       unless ($p4User);
	$p4Port       = $P4_PORT       unless ($p4Port);

	if ($p4Password) {
	    $p4Cmd .= "-u $p4User -P $p4Password";
	} else {
	    $p4Cmd .= " -u $p4User";    #Use Password Ticket
	}
	if ($p4Port) {
	    $p4Cmd .= " -p $p4Port";
	}

		#
	#   ####Now, Run Your Program
	#

	my $changeList = 69505;

	my $cmd = qq($p4Cmd -s describe -s $changeList);
	open (CHANGELIST, qq($cmd|)) or die qq(Can't run "$cmd"\n);

	while (<CHANGELIST>) {
	    #process it
	}

--
David Weintraub
david.weintraub at bankofamerica.com
david.weintraub at bofasecurities.com

________________________________

	From: p4perl-bounces at perforce.com
[mailto:p4perl-bounces at perforce.com] On Behalf Of
daniel.jacobs at symbian.com
	Sent: Wednesday, February 15, 2006 10:25 AM
	To: p4perl at perforce.com
	Subject: [p4perl] Using global options with P4Perl.

	Hi guys, 

	I'm using the P4Perl interface and I'm having trouble working
out how to use global options. For example, I'd like to run the command 

	p4 -s describe -s 69505 

	which prepends each line with text like this: 

	text: 
	text: 
	text: 
	text: 
	text: 
	text: 
	text: 
	text: 
	text: 
	text: 
	text: 
	text: 
	info1: 
	info1: 
	text: 
	exit: 

	I've tried things like 

	$p4->Run("-s", "describe", "-s", "69505"); 

	and 

	$p4->Run("-s describe", "-s", "69505"); 

	but to no avail. Any suggestions? 

	Dan 

	________________________________

		Don't miss out on your chance to...Do more with Symbian.
Make sure you visit the Symbian Stand, B20, at 3GSM 2006, 13-16
February, Barcelona, Spain. 

	************************************************************
********** Symbian Software Ltd is a company registered in England and
Wales with registered number 4190020 and registered office at 2-6
Boundary Row, Southwark, London, SE1 8HP, UK. This message is intended
only for use by the named addressee and may contain privileged and/or
confidential information.
If you are not the named addressee you should not disseminate, copy or
take any action in reliance on it. If you have received this message in
error please notify postmaster at symbian.com and delete the message and
any attachments accompanying it immediately. Neither Symbian nor any of
its Affiliates accepts liability for any corruption, interception,
amendment, tampering or viruses occurring to this message in transit or
for any message sent by its employees which is not in compliance with
Symbian corporate policy.
**********************************************************************
_______________________________________________
p4perl mailing list
p4perl at perforce.com
http://maillist.perforce.com/mailman/listinfo/p4perl