To make the new P4CLIENT setting apply to the next command executed with Run(), DefineClient() sets the value in the registry and then calls SetClient().

The following code illustrates how this method might be used to make a Windows client application start up with a default P4CLIENT setting.

client.Init( &e );
client.DefineClient( "default_workspace", &e );

To make the new P4HOST setting apply to the next command executed with Run(), DefineHost() sets the value in the registry and then calls SetHost().

The following code illustrates how this method might be used to make a Windows client application start up with a default P4HOST setting.

client.Init( &e );
client.DefineHost( "default_host", &e );

To make the new P4IGNORE setting apply to the next command executed with Run(), DefineIgnoreFile() sets the value in the registry and then calls SetIgnoreFile().

ClientApi::GetIgnore() ClientApi::GetIgnoreFile() ClientApi::SetIgnoreFile()

The following code illustrates how this method might be used to make a Windows client application start up with a default P4IGNORE setting.

# include "clientapi.h"

int main()
{
    ClientApi client;
    Error e;

    client.Init( &e );
    client.DefineIgnoreFile( ".p4ignore", &e );
}

To make the new P4PASSWD setting apply to the next command executed with Run(), DefinePassword() sets the value in the registry and then calls SetPassword().

DefinePassword() does not define a new server-side password for the user.

Call DefinePassword() with either the plaintext password, or its MD5 hash

The following code illustrates how this method might be used to make a Windows client application start up with a default P4PASSWD setting.

client.Init( &e );
client.DefinePassword( "default_pass", &e );

In order to make the new P4PORT setting apply to the next client connection opened with Init(), DefinePort() sets the value in the registry and then calls SetPort().

The following code illustrates how this method might be used to make a Windows client application automatically set itself to access a backup server if the primary server fails to respond. (This example assumes the existence of a backup server that perfectly mirrors the primary server.)

client.Init( &e );

if ( e.IsFatal() )
{
    e.Clear();
    ui.OutputError( "No response from server - switching to backup!\n" );
    client.DefinePort( "backup:1666", &e );
    client.Init( &e );
}

The first command to which the primary server fails to respond results in the error message and the program reinitializing the client to point to the server at backup:1666. Subsequent commands do not display the warning because the new P4PORT value has been set in the registry.

To make the new P4USER setting apply to the next command executed with Run(), DefineUser() sets the value in the registry and then calls SetUser().

The following code illustrates how this method might be used to make a Windows client application start up with a default P4USER setting.

client.Init( &e );
client.DefineUser( "default_user", &e );

Dropped() is usually called after Run(); it then checks whether the command completed successfully. If the Init() is only followed by one Run(), as in p4api.cc, calling Final() and then checking the Error is sufficient to see whether the connection was dropped. However, if you plan to make many calls to Run() after one call to Init(), Dropped() provides a way to check that the commands are completing without actually cleaning up the connection with Final().

The Dropped() method is useful if you want to reuse a client connection multiple times, and need to make sure that the connection is still alive.

For example, an application for stress-testing a Perforce server might run "p4 have" 10,000 times or until the connection dies:

ClientApi client;
MyClientUser ui;  //this ClientUser subclass doesn't output anything.
Error e;

client.Init( &e );
int count = 0;
while ( !( client.Dropped() ) && count < 10000 )
{
    count++;
    client.Run( "have", &ui );
}
printf( "Checked have list %d times.\n", count );
client.Final( &e ); // Clean up connection.

If the Dropped() result is true, the while loop ends. The actual error message remains inaccessible until after the call to client.Final() to close the connection and store the error.

Call this method after you are finished using the ClientApi object in order to clean up the connection. Every call to Init() must eventually be followed by exactly one call to Final().

The following example is a slight modification of p4api.cc, and reports the number of errors before the program exits:

client.Init( &e );

client.SetArgv( argc - 2, argv + 2 );
client.Run( argv[1], &ui );

printf( "There were %d errors.\n", client.Final( &e ) );

The return value of GetClient() is a fixed reference to this ClientApi object’s setting.

Assigning the return value to a StrPtr results in a StrPtr containing a Text() value that changes if the ClientApi object’s client setting changes.

Assigning the return value to a StrBuf copies the text in its entirety for future access, rather than simply storing a reference to data that might change later.

Under some circumstances, GetClient() calls GetHost() and returns that value - specifically, if no suitable P4CLIENT value is available in the environment, or previously set with SetClient(). (This is why, under the Perforce client, client name defaults to the host name if not explicitly set.)

In some instances, GetHost() does not return valid results until after a call to Init() - see the GetHost() documentation for details.

This example demonstrates the use of GetClient() and the difference between StrPtr’s and StrBuf’s.

ClientApi client;
StrPtr p;
StrBuf b;

client.Init();
client.SetClient( "one" );
p = client.GetClient();
b = client.GetClient();
client.SetClient( "two" );

printf( "Current client %s = %s\n", client.GetClient().Text(), p.Text() );
printf( "Previous client setting was %s\n", b.Text() );

Executing the preceding code produces the following output:

Current client two = two
Previous client setting was one

See GetClient() for more about the StrPtr return value.

If the P4CONFIG has not been set, GetConfig() returns “noconfig”.

The following example demonstrates the usage of GetConfig().

ClientApi client;

printf( "Current P4CONFIG is %s\n", client.GetConfig().Text() );

Executing the preceding code without having specified a configuration file produces the following output:

C:\perforce> a.out
Current P4CONFIG is noconfig

See GetClient() for more about the StrPtr return value.

If the working directory has been set by a call to SetCwd() or SetCwdNoReload(), subsequent calls to GetCwd() return that setting regardless of the actual working directory.

The following example demonstrates the usage of GetCwd().

ClientApi client;

printf( "Current directory is %s\n", client.GetCwd().Text() );

Executing the preceding code produces the following output:

C:\perforce> a.out
Current directory is c:\perforce

See GetClient() for more about the StrPtr return value.

In some instances, GetHost() is not valid until after the network connection has been established with Init(). GetHost() attempts to pull its value from earlier SetHost() calls, then from P4HOST in the environment, and then from the value of "hostname" returned by the client OS. If none of these is applicable, a reverse DNS lookup is performed, but the lookup will not work unless the connection has been established with Init().

To guarantee valid results, call GetHost() only after Init() or SetHost(). As GetHost() may sometimes be called during the execution of GetClient(), this warning applies to both methods.

As noted above, GetHost() does not necessarily return the actual hostname of the machine if it has been overridden by P4HOST or an earlier call to SetHost().

The following example demonstrates the usage of GetHost().

ClientApi client;
client.Init();

printf( "Client hostname is %s\n", client.GetHost().Text() );

Executing the preceding code produces the following output:

shire% a.out
Client hostname is shire

If P4IGNORE is not set, no paths are ignored.

ClientApi::DefineIgnoreFile() ClientApi::GetIgnoreFile() ClientApi::SetIgnoreFile()

This example demonstrates the use of GetIgnore().

if ( client->GetIgnore()->Reject( *clientPath,
                                      client->GetIgnoreFile() ) )
    {
        /* handling for ignored file */
    }
}

See GetClient() for more about the StrPtr return value.

If the P4IGNORE is unset, GetIgnoreFile() returns an uninitialized StrPtr.

ClientApi::DefineIgnoreFile() ClientApi::GetIgnore() ClientApi::SetIgnoreFile()

This example demonstrates the use of GetIgnoreFile().

# include "clientapi.h"

int main()
{
    ClientApi client;
    printf( "The current ignore file is '%s'\n",
            client.GetIgnoreFile().Text() );
}

Executing the preceding code produces output similar to the following:

The current ignore file is .p4ignore

See GetClient() for more about the StrPtr return value.

GetOs() returns one of “UNIX”, “vms”, “NT”, “Mac”, or null.

The following example demonstrates the usage of GetOs().

ClientApi client;

printf( "Client OS is %s\n", client.GetOs().Text() );

Executing the preceding code under Windows produces the following output:

C:\perforce> a.out
Client OS is NT

Executing the preceding code on a UNIX machine produces the following output:

shire$ a.out
Client OS is UNIX

See GetClient() for more about the StrPtr return value.

This method returns the password currently set on the client, which may or may not be the one set on the server for this user. The command "p4 passwd" sets P4PASSWD on the client machine to an MD5 hash of the actual password, in which case GetPassword() returns this MD5 hash rather than the plaintext version.

However, if the user sets P4PASSWD directly with the plaintext version, GetPassword() returns that plaintext version. In both instances, the result is the same as that displayed by "p4 set" or an equivalent command that displays the value of the P4PASSWD environment variable.

SetPassword() overrides the P4PASSWD value, and subsequent GetPassword() calls return the new value set by SetPassword() rather than the one in the environment.

The following example demonstrates the usage of GetPassword().

ClientApi client;

printf( "Your password is %s\n", client.GetPassword().Text() );

The following session illustrates the effect of password settings on GetPassword():

> p4 set P4PASSWD=p455w04d
> a.out
Your password is p455w04d

> p4 passwd
Enter new password:
Re-enter new password:
Password updated.

> a.out
Your password is 6F577E10961C8F7B519501097131787C

See GetClient() for more about the StrPtr return value.

If the environment variable P4PORT is unset, GetPort() sets the port to the default value of perforce:1666.

The following example demonstrates the usage of GetPort().

ClientApi client;

printf( "You're looking for a server at %s\n", \
         client.GetPort().Text() );

Executing the preceding code produces the following output:

You're looking for a server at perforce:1666

If the variable is unset, the return value is null. If there is a value, it will be a number in most cases, but in the form of a StrPtr rather than an int.

Call GetProtocol() only after a call to Run(), because protocol information is not available until after a call to Run(). Calling GetProtocol() before Run() results in a return value of null, which looks misleadingly like an indication that the variable is unset.

GetProtocol() reports only on variables set by the server, not variables set by the client with calls to SetProtocol().

The following example code checks whether the server is case-sensitive.

...
client.Init( &e );
...
client.Run();

if ( client.Dropped() )
{
    client.Final( &e );
}

if ( client.GetProtocol( "nocase" ) )
    printf( "Server case-insensitive.\n" );
else
    printf( "Server is case-sensitive.\n" );

See GetClient() for more about the StrPtr return value.

The following example demonstrates the usage of GetUser().

ClientApi client;

printf( "Your username is %s\n", client.GetUser().Text() );

Executing the preceding code as testuser produces the following output:

Your username is testuser

Init() must be called to establish a connection before any commands can be sent to the server. Each call to Init() must be followed by exactly one call to Final().

If an error occurs during Init(), it is most likely a connection error, with a severity of E_FATAL.

The following code from p4api.cc opens a connection with Init(), sets arguments, runs a command, and closes the connection with Final().

ClientUser ui;
ClientApi client;
Error e;

client.Init( &e );

client.SetArgv( argc - 2, argv + 2 );
client.Run( argv[1], &ui );
client.Final( &e );
return 0;

The func argument to Run() is the Perforce command to run, (for instance, info or files). Command arguments are not included and must be set separately with StrDict::SetArgv().

Initialize the connection with Init() before calling Run(), because without a connection, no commands can be sent to the server. Attempting to call Run() before Init() will probably result in a fatal runtime error.

Run() returns only after the command completes. Note that all necessary calls to ClientUser methods are made during the execution of Run(), as dictated by the server.

The code below runs p4 info, using ClientUser::OutputInfo() to display the results to the user. If a subclass of ClientUser is used here as the ui argument, that subclass’s implementation of OutputInfo() is used to display the results of the command.

ClientApi client;
ClientUser ui;
Error e;

client.Init( &e );
client.Run( "info", &ui );
client.Final( &e );

To establish the callback routine, you must call SetBreak() after ClientApi::Init().

KeepAlive::IsAlive()

The following example implements a custom IsAlive() that can be called three times before returning 0 and terminating the connection. If the call to run the changes command takes less than 1.5 seconds to complete on the server side, the program outputs the list of changes. If the call to run the changes command takes more than 1.5 seconds, the connection is interrupted.

#include <clientapi.h>

// subclass KeepAlive to implement a customized IsAlive function.
class MyKeepAlive : public KeepAlive
{
    public:
    int  IsAlive();
};

// Set up the interrupt callback. After being called 3 times,
// interrupt 3 times, interrupt the current server operation.
int   MyKeepAlive::IsAlive()
{
    static int counter = 0;
    if ( ++counter > 3 )
    {
        counter = 0;
        return( 0 );
    }
    return( 1 );
}

// Now test the callback
ClientUser ui;
ClientApi client;
MyKeepAlive cb;
Error e;

client.Init( &e );
client.SetBreak( &cb );   // SetBreak must happen after the Init
client.Run( "changes", &ui );
client.Final( &e );

SetClient() does not permanently set the P4CLIENT value in the environment or registry. The new setting applies only to commands executed by calling this ClientApi object’s Run() method.

The following example displays two client specifications by calling SetClient() between Run() commands.

ClientApi client;
ClientUser ui;
StrBuf sb1;
StrBuf sb2;

sb1 = "client_one";
sb2 = "client_two";
args[0] = "-o";

client.SetClient( &sb1 );
client.SetArgv( 1, args );
client.Run( "client", &ui );

client.SetClient( &sb2 );
client.SetArgv( 1, args );
client.Run( "client", &ui );

SetClient() does not permanently set the P4CLIENT value in the environment or registry. The new setting applies only to commands executed by calling this ClientApi object’s Run() method.

The following example displays two client specifications by calling SetClient() between Run() commands.

ClientApi client;
ClientUser ui;

char *args[1];
args[0] = "-o";

client.SetClient( "client_one" );
client.SetArgv( 1, args );
client.Run( "client", &ui );

client.SetClient( "client_two" );
client.SetArgv( 1, args );
client.Run( "client", &ui );

SetCwd() does not permanently set a new working directory in the client environment. The new setting applies only to commands executed by calling this ClientApi object’s Run() method.

The following code sets different working directories and displays them with p4 info.

ClientApi client;
ClientUser ui;
StrBuf sb1;
StrBuf sb2;

sb1 = "C:\one";
sb2 = "C:\two";

client.SetCwd( &sb1 );
client.Run( "info", &ui );

client.SetCwd( &sb2 );
client.Run( "info", &ui );

SetCwd() does not permanently set a new working directory in the client environment. The new setting applies only to commands executed by calling this ClientApi object’s Run() method.

The following code sets different working directories and displays them with p4 info.

ClientApi client;
ClientUser ui;

client.SetCwd( "C:\one" );
client.Run( "info", &ui );

client.SetCwd( "C:\two" );
client.Run( "info", &ui );

SetCwdNoReload() does not permanently set a new working directory in the client environment. The new setting applies only to commands executed by calling this ClientApi object’s Run() method.

Unlike SetCwd(), SetCwdNoReload() ignores any P4CONFIG files found in the new directory hierarchy.

The following code sets different working directories and displays them with p4 info.

ClientApi client;
ClientUser ui;
StrBuf sb1;
StrBuf sb2;

sb1 = "C:\one";
sb2 = "C:\two";
client.SetCwdNoReload( &sb1 );
client.Run( "info", &ui );

client.SetCwdNoReload( &sb2 );
client.Run( "info", &ui );

SetCwdNoReload() does not permanently set a new working directory in the client environment. The new setting applies only to commands executed by calling this ClientApi object’s Run() method.

Unlike SetCwd(), SetCwdNoReload() ignores any P4CONFIG files found in the new directory hierarchy.

The following code sets different working directories and displays them with p4 info.

ClientApi client;
ClientUser ui;

client.SetCwdNoReload( "C:\one" );
client.Run( "info", &ui );

client.SetCwdNoReload( "C:\two" );
client.Run( "info", &ui );

SetHost() does not permanently change the host name of the client or set P4HOST in the environment. The new setting applies only to commands executed by calling this ClientApi object’s Run() method.

The following example sets different hostnames and displays them with p4 info.

ClientApi client;
ClientUser ui;
StrBuf sb1;
StrBuf sb2;

sb1 = "magic";
sb2 = "shire";

client.SetHost( &sb1 );
client.Run( "info", &ui );

client.SetHost( &sb2 );
client.Run( "info", &ui );

SetHost() does not permanently change the host name of the client or set P4HOST in the environment. The new setting applies only to commands executed by calling this ClientApi object’s Run() method.

The following example sets different hostnames and displays them with p4 info.

ClientApi client;
ClientUser ui;

client.SetHost( "magic" );
client.Run( "info", &ui );

client.SetHost( "shire" );
client.Run( "info", &ui );

SetIgnoreFile() does not permanently set the P4IGNORE value in the environment or registry. The new setting applies only to commands executed by calling this ClientApi object’s Run() method.

ClientApi::DefineIgnoreFile() ClientApi::GetIgnore() ClientApi::GetIgnoreFile()

The following example sets an ignore file location by calling SetIgnoreFile().

# include "clientapi.h"

int main()
{
    ClientApi client;
    StrBuf sb;

    sb = ".p4ignore";
    client.SetIgnoreFile( &sb; );
}

SetIgnoreFile() does not permanently set the P4IGNORE value in the environment or registry. The new setting applies only to commands executed by calling this ClientApi object’s Run() method.

ClientApi::DefineIgnoreFile()> <<clientapi.getignore,ClientApi::GetIgnore() ClientApi::GetIgnoreFile()

The following example sets a ticket file location by calling SetIgnoreFile().

# include "clientapi.h"

int main()
{
    ClientApi client;

    client.SetIgnoreFile( ".p4ignore" );
}

SetPassword() does not permanently change the P4PASSWD value in the environment, nor does it in any way change the password that has been set on the server. The new setting applies only to authentication attempts for commands executed by calling this ClientApi object’s Run() method.

The following trivial example demonstrates how to hard-code a password into an application without making it (immediately) user-visible.

ClientApi client;
ClientUser ui;
StrBuf sb;

sb = "p455w04d";

client.SetPassword( &sb );
client.SetArgv( argc - 2, argv + 2 );
client.Run( argv[1], &ui );

SetPassword() does not permanently change the P4PASSWD value in the environment, nor does it in any way change the password that has been set on the server. The new setting applies only to authentication attempts for commands executed by calling this ClientApi object’s Run() method.

The following trivial example demonstrates how to hard-code a password into an application without making it (immediately) user-visible.

ClientApi client;
ClientUser ui;

client.SetPassword( "p455w04d" );
client.SetArgv( argc - 2, argv + 2 );
client.Run( argv[1], &ui );

SetPort() does not permanently change the P4PORT value in the environment. The new setting applies only to new connections established by calling this ClientApi object’s Init() method.

The following example demonstrates setting a new port value before initializing the connection.

ClientApi client;
Error e;
StrBuf sb;

sb = "ssl:magic:1666";

client.SetPort( &sb );
client.Init( &e );

SetPort() does not permanently change the P4PORT value in the environment. The new setting applies only to new connections established by calling this ClientApi object’s Init() method.

The following example demonstrates setting a new port value before initializing the connection.

ClientApi client;
Error e;

client.SetPort( "magic:1666" );
client.Init( &e );

SetProg() sets the identity of a client application as reported by the p4 monitor command, or as recorded by server logging.

Call SetProg() before calling Init().

ClientApi::SetVersion()

The following example appears as MyApp in the output of p4 monitor show.

ClientApi client;
ClientUser ui;
StrBuf sb;
Error e;

sb.Set( "MyApp" );

client.Init( &e );
client.SetProg( &sb );
client.Run( "info", &ui );

SetProg() sets the identity of a client application as reported by the p4 monitor command, or as recorded by server logging.

Call SetProg() before calling Init().

ClientApi::SetVersion()

The following example appears as MyApp in the output of p4 monitor show.

ClientApi client;
ClientUser ui;
Error e;

client.Init( &e );
client.SetProg( "MyApp" );
client.Run( "info", &ui );

SetProtocol() must be called before the connection is established with Init().

The following variables are supported by SetProtocol():

By default, the value of the api protocol variable matches the version of the API with which you built your application; under most circumstances, you do not need to set the protocol version from within your application. If you are concerned about changes in server behavior, you can manually set the api variable in order to protect your code against such changes.

For instance, the "p4 info" command supports tagged output as of server release 2003.2, and changes to this format were made in 2004.2. Code requesting tagged output from "p4 info" that was compiled against the 2003.1 API library may break (that is, start producing tagged output) when running against a 2003.2 or newer server. To prevent this from happening, set api to the value corresponding to the desired server release.

The following example demonstrates the use of SetProtocol() to enable tagged output. The result of this call is that the ClientUser object uses OutputStat() to handle the output, rather than OutputInfo().

ClientApi client;
Error e;

client.SetProtocol( "tag", "" );
client.Init( &e );
client.Run( "branches", &ui );
client.Final( &e );

The following code illustrates how to ensure forward compatibility when compiling against newer versions of the Perforce API or connecting to newer Perforce servers.

ClientApi client;
Error e;

printf( "Output is tagged depending on API or server level.\n" );
client.SetProtocol( "tag", "" ); // request tagged output
client.Init( &e );
client.Run( "info", &ui );
client.Final( &e );

printf( "Force 2003.1 behavior regardless of API or server level.\n" );
client.SetProtocol( "tag", "" );   //request tagged output
client.SetProtocol( "api", "55" ); // but force 2003.1 mode (untagged)
client.Init( &e );
client.Run( "info", &ui );
client.Final( &e );

printf( "Request 2003.2 output if API and server support it.\n" );
client.SetProtocol( "tag", "");   // request tagged output
client.SetProtocol( "api", "56"); // force 2003.2 mode (tagged)
client.Init( &e );
client.Run( "info", &ui );
client.Final( &e );

The "p4 info" command supports tagged output only as of server release 2003.2. In the example, the first Run() leaves api unset; if both the client API and Perforce server support tagged output for p4 info (that is, if you link this code with the 2003.2 or later API and run it against a 2003.2 or later server), the output is tagged. If you link the same code with the libraries from the 2003.1 release of the API, however, the first Run() returns untagged output even if connected to a 2003.2 server. By setting api to 55, the second Run() ensures 2003.1 behavior regardless of API or server level. The third call to Run() supports 2003.2 behavior against a 2003.2 server and protects against future changes.

SetProtocolV() functions identically to SetProtocol(), except that its argument is a single string of the format variable=value.

The following example demonstrates the use of SetProtocolV() to enable tagged output. The result is that the ClientUser object uses OutputStat() to handle the output, rather than OutputInfo().

ClientApi client;
Error e;

client.SetProtocolV( "tag=" );
client.Init( &e );
client.Run( "branches", &ui );
client.Final( &e );

SetTicketFile() does not permanently set the P4TICKETS value in the environment or registry. The new setting applies only to commands executed by calling this ClientApi object’s Run() method.

The following example sets a ticket file location by calling SetTicketFile().

ClientApi client;
StrBuf sb;

sb = "/tmp/ticketfile.txt";
client.SetTicketFile( &sb );

SetTicketFile() does not permanently set the P4TICKETS value in the environment or registry. The new setting applies only to commands executed by calling this ClientApi object’s Run() method.

The following example sets a ticket file location by calling SetTicketFile().

ClientApi client;

client.SetTicketFile( "/tmp/ticketfile.txt" );

Unless you pass the ClientUser object to the Run() method, you must first call SetUi(). The new setting applies to commands executed by calling this ClientApi object’s Run() method.

The following example illustrates two ways to run p4 info:

ClientApi client;
ClientUser ui;

client.Run( "info", &ui );

client.SetUi( &ui );
client.Run( "info" );

SetUser() does not permanently set the P4USER value in the environment or registry. Calling this method is equivalent to using the "-u" global option from the command line to set the user value for a single command, with the exception that a single ClientApi object can be used to invoke multiple commands in a row.

If the user setting is to be in effect for the command when it is executed, you must call SetUser() before calling Run().

The following example displays two user specifications by calling SetUser() between Run() commands.

ClientApi client;
Error e;
StrBuf sb1;
StrBuf sb2;

sb1 = "user1";
sb2 = "user2";

char *args[1];
args[0] = "-o";

client.SetUser( &sb1 );
client.SetArgv( 1, args );
client.Run( "user", &ui );

client.SetUser( &sb2 );
client.SetArgv( 1, args );
client.Run( "user", &ui );

SetUser() does not permanently set the P4USER value in the environment or registry. Calling this method is equivalent to using the "-u" global option from the command line to set the user value for a single command, with the exception that a single ClientApi object can be used to invoke multiple commands in a row.

If the user setting is to be in effect for the command when it is executed, you must call SetUser() before calling Run().

The following example displays two user specifications by calling SetUser() between Run() commands.

ClientApi client;
Error e;

char *args[1];
args[0] = "-o";

client.SetUser( "user1" );
client.SetArgv( 1, args );
client.Run( "user", &ui );

client.SetUser( "user2" );
client.SetArgv( 1, args );
client.Run( "user", &ui );

SetVersion() sets the version number of a client application as reported by the p4 monitor -e command, or as recorded by server logging.

If a client application compiled with version 2005.2 or later of the API does not call SetVersion(), then the version string reported by p4 monitor -e (and recorded in the server log) defaults to the api value appropriate for the server level as per SetProtocol().

Call SetVersion() after calling Init() and before each call to Run().

ClientApi::SetProtocol() ClientApi::SetProg()

The following example appears as 2005.2 in the output of p4 monitor show -e.

ClientApi client;
ClientUser ui;
StrBuf sb;
Error e;

sb.Set( "2005.2" );

client.Init( &e );
client.SetVersion( &sb );
client.Run( "info", &ui );

SetVersion() sets the version number of a client application as reported by the p4 monitor -e command, or as recorded by server logging.

If a client application compiled with version 2005.2 or later of the API does not call SetVersion(), then the version string reported by p4 monitor -e (and recorded in the server log) defaults to the pass:[<literal>api</literal> value appropriate for the server level as per SetProtocol().

Call SetVersion() after calling Init() and before each call to Run().

ClientApi::SetProtocol() ClientApi::SetProg()

The following example appears as 2005.2 in the output of p4 monitor show -e.

ClientApi client;
ClientUser ui;
Error e;

client.Init( &e );
client.SetVersion( "2005.2" );
client.Run( "info", &ui );

The API calls this method on command startup, supplying your implementation with a description and a client progress unit type. The units in which client progress is measured are defined in clientprog.h as follows:

ClientUser::CreateProgress() ClientUser::ProgressIndicator() ClientProgress::Done() ClientProgress::Total() ClientProgress::Update()

Create a subclass of ClientProgress and define an implementation of Description(), even if it is a trivial implementation:

void MyProgress::Description( const StrPtr *desc, int units )
{
    printf( "Starting command:\n" );
}

The API calls Done() on command completion with 0 for success, or 1 for failure.

ClientUser::CreateProgress() ClientUser::ProgressIndicator() ClientProgress::Description() ClientProgress::Total() ClientProgress::Update()

To change the way completed actions are reported, create a subclass of ClientProgress and define an alternate implementation of Done(). For example, to output "Command failed" or "Command completed" upon success or failure, implement Done() as follows:

void MyProgress::Done( int fail )
{
    printf( fail ? "Command failed\n" : "Command completed\n");
}

The API calls this method if and when it has determined the number of client progress units, as defined by Description(), are to be processed during the command.

If the total number of expected units changes during the lifetime of a command, the API may call this method more than once. (The total number of expected units is not the same as the number of remaining units; certain commands may result in multiple calls to this method as the server determines more about the amount of data to be retrieved.)

ClientUser::CreateProgress() ClientUser::ProgressIndicator() ClientProgress::Description() ClientProgress::Done() ClientProgress::Update()

To report how many progress units are expected, create a subclass of ClientProgress and define an alternate implementation of Total().

For example, the following method outputs the number of units expected and is called when, if, and as the total number of expected units changes over the lifetime of the command:

void MyProgress::Total( long units )
{
    printf( "Now expecting %l units\n" );
}

The API calls the Update() method periodically during the life of a command and reports on the number of client progress units processed. (Because a million calls for an update of one million 1024-byte files would be prohibitive, not every unit of progress is reported.) Instead, the API calls this method periodically depending on a combination of elapsed time and number of client progress units processed.

In addition to reporting progress in terms of the units defined by Description(), if Update() returns non-zero, the API interprets it as a user request to cancel the operation.

ClientUser::CreateProgress() ClientUser::ProgressIndicator() ClientProgress::Description() ClientProgress::Done() ClientProgress::Total()

To report on units processed, create a subclass of ClientProgress and define an alternate implementation of Update(). A trivial implementation ignores cancel requests by always returning 0; a more useful implementation might resemble the following:

void MyProgress::Update( long units )
{
    if ( cancelclicked() ) // has anyone clicked the Cancel button?
    {
        return 1; // yes, user wishes to cancel
    }
    else
    {
        displayGUI( units ); // show how many units have been processed
        return 0; // user has not requested cancel, continue processing
    }
}

To enable progress reporting for a command, create a ClientProgress object and then implement ProgressIndicator() to return 0 or 1 depending on whether or not you want to enable the progress indicator. (You typically implement ProgressIndicator() to return 1, and call it only when a progress indicator is desired.)

The API calls this method with the appropriate ProgressType as defined in clientprog.h. The following ProgressTypes can be reported:

ClientUser::ProgressIndicator() ClientProgress::Description() ClientProgress::Done() ClientProgress::Total() ClientProgress::Update()

This method is used by p4 diff and to display diffs from an interactive p4 resolve. If no external diff program is specified, the diff is carried out with a Diff object (part of the Perforce C/C++ API); otherwise, Diff() simply calls the specified external program.

As with Merge(), the external program is invoked with ClientUser::RunCmd().

If doPage is nonzero and the P4PAGER environment variable is set, the output is piped through the executable specified by P4PAGER.

ClientUser::RunCmd()

In its default implementation, this method is called by an application when p4 diff is run. For example:

p4 diff -dc file.c

results in a call to Diff() with the arguments:

The diff is performed by creating a Diff object, giving it f1 and f2 as its inputs, and -c as its flag. The end result is sent to stdout. If either of the files is binary, the message “files differ” is printed instead.

Selecting the “d” option during an interactive p4 resolve also calls the Diff() method, with the doPage argument set to 1.

If the environment variable P4PAGER or PAGER is set, then setting doPage to 1 causes the diff output to be fed through the specified pager. If P4PAGER and PAGER are unset, dopage has no effect and the resolve routine displays the diff output normally.

To enable an application to override the default diff routine, create a subclass of ClientUser that overrides the Diff() method, and use this subclass in place of ClientUser.

As an example, suppose that you have a special diff program designed for handling binary files, and you want p4 diff to use it whenever asked to diff binary files (rather than display the default “files differ…​”).

Furthermore, you want to keep your current P4DIFF setting for the purpose of diffing text files, so you decide to use a new environment variable called P4DIFFBIN to reference the binary diff program. If P4DIFFBIN is set and one of the files is non-text, the P4DIFFBIN program is invoked as P4DIFF is in the default implementation. Otherwise, the default implementation is called.

Most of the following code is copied and pasted from the default implementation.

MyClientUser::Diff( FileSys *f1, FileSys *f2, int doPage, char *df, Error *e )
{
    const char *diff = enviro->Get( "P4DIFFBIN" );
    if ( diff && ( !f1->IsTextual() || !f2->IsTextual() ) ) // binary diff
    {
        if ( !df || !*df )
        {
            RunCmd( diff, 0, f1->Name(), f2->Name(), 0, pager, e );
        }
        else
        {
            StrBuf flags;
            flags.Set( "-", 1 );
            flags << df;
            RunCmd( diff, flags. Text(), f1->Name(), f2->Name(), 0, pager, e );
        }
    }
    else ClientUser::Diff( f1, f2, doPage, df, e );
}

This method works like Diff(), but instead of sending data to the standard output, writes the data to the specified output file.

The FileSys * argument to Edit() refers to a client temp file that contains the specification that is to be given to the server. Edit() does not send the file to the server; its only job is to modify the file. In the default implementation, Edit() does not return until the editor has returned.

There is also a three-argument version of Edit(), for which the default two-argument version is simply a wrapper. The three-argument version takes an Enviro object as an additional argument, and the two-argument version simply passes the member variable enviro as this argument. Only the two-argument version is virtual.

The p4 client command is one of several Perforce commands that use ClientUser::Edit() to allow the user to modify a specification. When the command is executed, the server sends the client specification to the client machine, where it is held in a temp file. Edit() is then called with that file as an argument, and an editor is spawned. When the editor closes, Edit() returns, and the temp file is sent to the server.

To allow modification of a specification by other means, such as a customized dialog or an automated process, create a subclass of ClientUser that overrides the Edit() method and use this subclass in place of ClientUser.

Suppose that you have already written a function that takes a FileSys as input, opens a custom dialog, and returns when the file has been modified. Replace the body of Edit() in your subclass with a call to your function, as follows:

void MyClientUser::Edit( FileSys *f1, Error *e )
{
    MyDialog( f1 );
}

The default implementation of ErrorPause() consists solely of calls to OutputError() and Prompt().

One situation that results in a call to ErrorPause() is an incorrectly edited specification; for example:

> p4 client
...
Error in client specification.
Error detected at line 31.
Wrong number of words for field 'Root'.
Hit return to continue...

In this instance, the first three lines of output were the errBuf argument to ErrorPause(); they were displayed using OutputError().

To display an error and prompt for confirmation within a GUI application, create a subclass of ClientUser that overrides ErrorPause() and use this subclass in place of ClientUser.

Suppose that you have a function MyWarning() that takes a char * as an argument, and displays the argument text in an appropriate popup dialog that has to be clicked to be dismissed. You can implement ErrorPause() as a call to this function, as follows:

void MyClientUser::ErrorPause( char *errBuf, Error *e )
{
    MyWarning( errBuf );
}

Within a GUI, the warning text and "OK" button are probably bundled into a single dialog, so overriding ErrorPause() is a better approach than overriding OutputError() and Prompt() separately.

This method is a wrapper for FileSys::Create().

ClientUser::File() is generally called whenever it’s necessary to manipulate files in the client workspace. For example, a p4 sync, p4 edit, or p4 revert makes one call to File() for each workspace file with which the command interacts.

An alternate implementation might return a subclass of FileSys. For example, if you have defined a class MyFileSys and want your MyClientUser class to use members of this class rather than the base FileSys, reimplement File() to return a MyFileSys instead:

FileSys * MyClientUser::File( FileSysType type )
{
    return MyFileSys::Create( type );
}

This function is called by the server at the end of every Perforce command, but in its default implementation, it has no effect. The default implementation of this function is empty - it takes nothing, does nothing, and returns nothing.

To trigger an event after the completion of a command, create a subclass of ClientUser and provide a new implementation of Finished() that calls that event.

For example, if you want your application to beep after each command, put the command into Finished(), as follows.

void MyClientUser::Finished()
{
    printf( "Finished!\n%c", 7 );
}

The default implementation formats the error with Error::Fmt() and outputs the result with OutputError().

2002.1 and newer servers do not call HandleError() to display errors. Instead, they call Message(). The default implementation of Message() calls HandleError() if its argument is a genuine error; as a result, older code that uses HandleError() can be used with the newer API and newer servers so long as the default implementation of Message() is retained.

HandleError() is called whenever a command encounters an error. For example:

> p4 files nonexistent
nonexistent - no such file(s).

In this case, the Error object given to HandleError() contains the text "nonexistent - no such file(s)." and has a severity of 2 (E_WARN).

To handle errors in a different way, create a subclass of ClientUser with an alternate implementation of HandleError().

For example, if you want an audible warning on a fatal error, implement HandleError() as follows:

void MyClientUser::HandleError( Error *err )
{
    if ( err->IsFatal() ) printf ( "Fatal error!\n%c", 7 );
}

This function is called by p4 resolve when the “?” option is selected during an interactive resolve. The default implementation displays the help text given to it, one line at a time.

The default implementation is called in order to display the "merge options" block of help text during a resolve by dumping the text to stdout.

To display the resolve help text in another manner, create a subclass of ClientUser with an alternate implementation of Help().

For example, suppose you’d like a helpful message about the meaning of "yours" and "theirs" to be attached to the help message. Define the method as follows:

void MyClientUser::Help( const char *const *help )
{
    for ( ; *help; help++ )
        printf( "%s\n", *help );
    printf( "Note: In integrations, yours is the target file, \
             theirs is the source file.\n" );
}

Any command that edits a specification can take the -i option; this method supplies the data for the specification. In the default implementation, the data comes from stdin, but an alternate implementation can accept the data from any source. This method is the only way to send a specification to the server without first putting it into a local file.

The default implementation is called during a normal invocation of p4 client -i.

p4 client -i < clispec.txt

In this example, clispec.txt is fed to the command as stdin. Its contents are appended to the StrBuf that is given as an argument to InputData(), and this StrBuf is given to the server after InputData() returns.

To read the data from a different source, create a subclass of ClientUser with an alternate implementation of InputData().

For example, suppose that you want to be able to edit a client specification without creating a local temp file. You’ve already written a function which generates the new client specification and stores it as a StrBuf variable in your ClientUser subclass. To send your modified client specification to the server when running p4 client -i with your modified ClientUser, implement InputData() to read data from that StrBuf.

The example below assumes that the subclass MyClientUser has a variable called mySpec that already contains the valid client specification before running p4 client -i.

void MyClientUser::InputData( StrBuf *buf, Error *e )
{
    buf->Set( mySpec );
}

Merge() is called if the “m” option is selected during an interactive resolve. Merge() does not call the Perforce merge program; it merely invokes external merge programs (including P4Merge as well as third-party tools). External merge programs must be specified by an environment variable, either P4MERGE or MERGE. Merge() returns after the external merge program exits.

As in Diff(), the external program is invoked using ClientUser::RunCmd().

ClientUser::RunCmd()

When the "merge" option is selected during an interactive resolve, the file arguments to Merge() are as follows:

These file arguments correspond exactly to the command-line arguments passed to the merge tool.

After you "accept" the merged file (with “ae”), the "result" temp file is copied into the “leg2” or "yours" workspace file, and this is the file that is submitted to the depot.

To change the way that external merge programs are called during a resolve, create a subclass of ClientUser with an alternate implementation of Merge().

For example, suppose that one of your favorite merge tools, “yourmerge”, requires the “result” file as the first argument. Rather than wrapping the call to the merge tool in a script and requiring your users to set P4MERGE to point to the script, you might want to provide support for this tool from within your application as follows:

void MyClientUser::Merge(
    FileSys *base,
    FileSys *leg1,
    FileSys *leg2,
    FileSys *result,
    Error *e )
{
    char *merger;

    if ( !( merger = enviro->Get( "P4MERGE" ) ) &&
         !( merger = getenv( "MERGE" ) ) )
    {
        e->Set( ErrClient::NoMerger );
        return;
    }

    if ( strcmp( merger, "yourmerge" ) == 0 )
    {
        RunCmd( merger, result->Name(), base->Name(),
                leg1->Name(), leg2->Name(), 0, e );
    }
    else
    {
        RunCmd( merger, base->Name(), leg1->Name(),
                leg2->Name(), result->Name(), 0, e );
    }
}

Message() is used by 2002.1 and later servers to display information or errors resulting from Perforce commands. Earlier versions of the Perforce server call OutputInfo() to display information, and HandleError() to display errors.

The default implementation of Message() makes calls to OutputInfo() or HandleError() as appropriate. If you want your application to be compatible with pre-2002.1 servers, use this default implementation of Message() - newer servers will call Message(), and older servers will call OutputInfo() and HandleError() directly.

If you re-implement Message() to handle errors and information in a different way, be advised that older servers will still call OutputInfo() and HandleError() rather than your Message() method.

> p4 files //depot/proj/...
//depot/proj/file.c#1 - add change 456 (text)

In this example, the server passes a single Error object to the ClientUser's Message() method, with a severity of E_INFO and text "//depot/proj/file.c#1 - add change 456 (text)". The default Message() method detects that this was an "info" message, and passes the text to OutputInfo(), which by default sends the text to stdout.

To handle messages differently, subclass ClientUser and re-implement the Message() method (see the preceding note on interoperability with old servers if you do this).

For example, to take all server messages and load them into a StrBuf that is a member of your ClientUser class, use the following:

void MyClientUser::Message( Error *err )
{
    StrBuf buf;
    err->Fmt( buf, EF_PLAIN );
    myBuf.Append( buf );
}

The default implementation of OutputBinary() writes the contents of a binary file to stdout. A call to OutputBinary() is typically the result of running p4 print on a binary file:

p4 print //depot/file.jpg > newfile.jpg

To modify the way in which binary files are output with p4 print, create a subclass of ClientUser with an alternate implementation of OutputBinary().

For example, suppose that you want PDF files to be printed to stdout as plain text. Add the following code (that checks to see if the file is PDF and, if so, calls a hypothetical OutputPDF() function to output PDFs to stdout) to the beginning of your implementation of OutputBinary().

void MyClientUser::OutputBinary( const char *data, int length )
{
    static unsigned char pdfFlag[] = { '%', 'P', 'D', 'F', '-' };
    if ( length >= 5 && memcmp( data, pdfFlag, sizeof( pdfFlag ) ) )
         OutputPDF( data, length );
    else
        ClientUser::OutputBinary( data, length );
}

The default implementation sends its argument to stderr. OutputError() is called by functions like HandleError().

Because the default implementation of HandleError() calls it, OutputError() is responsible for printing every error message in Perforce. For example:

p4 files //nonexistent/...
nonexistent - no such file(s).

In this case, the argument to OutputError() is the array containing the error message "nonexistent - no such file(s)."

To change the way error messages are displayed, create a subclass of ClientUser and define an alternate implementation of OutputError().

For example, to print all error messages to stdout rather than stderr, and precede them with the phrase “!!ERROR!!”, implement OutputError() as follows:

void MyClientUser::OutputError( const char *errBuf )
{
    printf( "!!ERROR!! " );
    fwrite( errBuf, 1, strlen( errBuf ), stdout );
}

OutputInfo() is called by the server during most Perforce commands; its most common use is to display listings of information about files. Any output not printed with OutputInfo() is typically printed with OutputText(). Running p4 -s <command> indicates whether any given line of output is "info" or "text".

In the default implementation of OutputInfo(), one “…​” string is printed per "level". Values given as "levels" are either 0, 1, or 2. The "data" passed is generally one line, without a line break; OutputInfo() adds the newline when it prints the output.

To capture information directly from Perforce commands for parsing or storing rather than output to stdout, it is usually necessary to use an alternate implementation of OutputInfo().

2002.1 and newer servers do not call OutputInfo() to display information. Instead, they call Message(). The default implementation of Message() calls OutputInfo() if its argument represents information instead of an error; older code that uses OutputInfo() can be used with the newer API and newer servers, so long as the default implementation of Message() is retained.

The p4 filelog command produces tabular output:

> p4 filelog final.c
//depot/final.c
... #3 change 703 edit on 2001/08/24 by testuser@shire (text) 'fixed'
... ... copy into //depot/new.c#4
... #2 change 698 edit on 2001/08/24 by testuser@shire (text) 'buggy'
... ... branch into //depot/middle.c#1
... #1 change 697 branch on 2001/08/24 by testuser@shire (text) 'test'
... ... branch from //depot/old.c#1,#3

Each line of output corresponds to one call to OutputInfo(). The first line of output has a level of '0', the line for each revision has a level of '1', and the integration record lines have levels of '2'. (The actual "data" text for these lines does not include the “…​” strings.)

To alter the way in which "info" output from the server is handled, create a subclass of ClientUser and provide an alternate implementation of OutputInfo().

For example, to capture output in a set of StrBuf variables rather than display it to stdout, your ClientUser subclass must contain three StrBufs, one for each level of info output, as follows:

void MyClientUser::OutputInfo( char level, const char *data )
{
    switch( level )
    {
        default:
        case '0':
            myInfo0.Append( data );
            myInfo0.Append( "\n" );
            break;
        case '1':
            myInfo1.Append( data );
            myInfo1.Append( "\n" );
            break;
        case '2':
            myInfo2.Append( data );
            myInfo2.Append( "\n" );
            break;
    }
}

Normally, the only Perforce command that sends output through OutputStat() is p4 fstat, which always returns tagged output. Some other commands can be made to return tagged output by setting the "tag" protocol variable, in which case the output is in the form of a StrDict suitable for passing to OutputStat() for processing.

It is generally easier to deal with tagged output than it is to parse standard output. The default implementation of OutputStat() passes each variable/value pair in the StrDict to OutputInfo() as a line of text with a level of "1", with the exception of the "func" var, which it skips. Alternate implementations can use tagged output to extract the pieces of information desired from a given command.

Consider the following output from p4 fstat:

> p4 fstat file.c
... depotFile //depot/file.c
... clientFile c:\depot\file.c
... isMapped
... headAction integrate
... headType text
... headTime 998644337
... headRev 10
... headChange 681
... headModTime 998643970
... haveRev 10

The StrDict passed to OutputStat() consists of eight variable/value pairs, one for each line of output, plus a "func" entry, which is discarded by the default implementation of OutputStat(). Other commands can be made to return tagged output through OutputStat() by using the -Ztag global option at the command line.

To process tagged output differently, create a subclass of ClientUser with an alternate implementation of OutputStat(). The following simple example demonstrates how the “headRev” and “haveRev” variables resulting from an “fstat” command can be easily extracted and manipulated.

Other commands provide StrDicts with different variable/value pairs that can be processed in similar ways; use p4 -Ztag command to get an understanding for what sort of information to expect.

void MyClientUser::OutputStat( StrDict *varList )
{
    StrPtr *headrev;
    StrPtr *haverev;

    headrev = varList->GetVar( "headRev" );
    haverev = varList->GetVar( "haveRev" );

    printf( "By default, revision numbers are returned as strings:\n" );
    printf( "  Head revision number: %s\n", headrev->Text() );
    printf( "  Have revision number: %s\n", haverev->Text() );

    printf( "but revision numbers can be converted to integers:\n" );
    printf( "  Head revision number: %d\n", headrev->Atoi() );
    printf( "  Have revision number: %d\n", haverev->Atoi() );
}

The most common usage of OutputText() is in running p4 print on a text file.

> p4 print -q file.txt
This is a text file.
It is called "file.txt"

The arguments to OutputText() in the preceding example are the pointer to the first character in the file contents, and the length of the file in bytes.

To alter the way in which OutputText() handles text data, create a subclass of ClientUser and provide an alternate implementation of OutputText().

For example, suppose that your ClientUser subclass contains a StrBuf called myData, and you want to store the data in this StrBuf rather than dump it to stdout.

void MyClientUser::OutputText( const char *data, int length )
{
    myData.Set( data, length );
}

After you have created a ClientProgress object with CreateProgress(), you must also implement ProgressIndicator() to return 0 or 1 depending on whether or not you want to report progress.

ClientUser::CreateProgress() ClientProgress::Description() ClientProgress::Done() ClientProgress::Total() ClientProgress::Update()

The typical implementation of ProgressIndicator() returns 1, and you call it when you wish to enable progress reporting:

MyUserProgress::ProgressIndicator()
{
    return 1;
}

Prompt() is used in the default implementation of HandleError() to prompt the user to correct the error. Prompt() is also used by the interactive resolve routine to prompt for options.

Consider the following user interaction with p4 resolve:

> p4 resolve file.c
c:\depot\file.c - merging //depot/file.c#2,#10
Diff chunks: 0 yours + 1 theirs + 0 both + 0 conflicting
Accept(a) Edit(e) Diff(d) Merge (m) Skip(s) Help(?) [at]: at

In the above example, the "msg" argument to Prompt() is the “Accept…​[at\]:” string. The response, "at", is placed into the "rsp" StrBuf, which is sent to the server and processed as "accept theirs".

To alter the behavior of Prompt(), create a subclass of ClientUser and provide an alternate implementation of Prompt().

For example, suppose that you are writing a GUI application and want each option in the interactive resolve to appear in a dialog box. A function called MyDialog() to create a dialog box containing the text of its argument and a text field, and return a character array with the user’s response, would look like this:

void MyClientUser::Prompt( const StrPtr &msg, StrBuf &buf, \
                           int noEcho, Error *e )
{
    buf.Set( MyDialog( msg.Text() ) );
}

RunCmd() is called when the client needs to call an external program, such as a merge or diff utility. RunCmd() stores any resulting errors in the specified Error object.

If you select "d" for "Diff" during an interactive resolve, and both P4DIFF and P4PAGER are set in your environment, RunCmd() is called with the following arguments:

The P4DIFF program is called with the two file names as arguments, and the output is piped through the P4PAGER program.

See the examples for Diff() and Merge() for code illustrating the use of RunCmd().

Clear() can be used if you need to clear an Error after having handled it in a way that does not automatically clear it.

The following code attempts to establish a connection to a nonexistent server, displays the error’s severity, clears the error, and shows that the error has been cleared:

ClientApi client;
Error e;

client.SetPort( "bogus:12345" );
client.Init( &e );

printf( "Error severity after Init() is is %d.\n", e.GetSeverity() );
e.Clear();
printf( "Error severity after Clear() is %d.\n", e.GetSeverity() );

Executing the preceding code produces the following output:

Error severity after Init() is 4.
Error severity after Clear() is 0.

Dump() can be used to determine the exact nature of an Error that is being handled. Its primary use is in debugging, as the nature of the output is more geared towards informing the developer than helping an end user.

The following code attempts to establish a connection to a nonexistent server, and dumps the resulting error:

ClientApi client;
Error e;

client.SetPort( "bogus:12345" );
client.Init( &e );

e.Dump( "example" );

Executing the preceding code produces the following output:

Error example 0012FF5C
   Severity 4 (error)
   Generic 38
   Count 3
      0: 1093012493 (sub 13 sys 3 gen 38 args 1 sev 4 code 3085)
      0: %host%: host unknown.
      1: 1093012492 (sub 12 sys 3 gen 38 args 1 sev 4 code 3084)
      1: TCP connect to %host% failed.
      2: 1076240385 (sub 1 sys 8 gen 38 args 0 sev 4 code 8193)
      2: Connect to server failed; check $P4PORT.
      host = bogus
      host = bogus:12345

The result of Fmt() is suitable for displaying to an end user; this formatted text is what the command line client displays when an error occurs.

If an error has no severity (E_EMPTY), Fmt() returns with no change to the StrBuf.

If the error has severity of info (E_INFO), the StrBuf is formatted.

If the error has any higher severity, the StrBuf argument passed to Fmt() is cleared and then replaced with the formatted error.

The following example code displays an error’s text:

if ( e.Test() )
{
    StrBuf msg;
    e.Fmt( &msg );
    printf( "ERROR:\n%s", msg.Text() );
}

The result of Fmt() is suitable for displaying to an end user; this formatted text is what the command line client displays when an error occurs.

If an error has no severity (E_EMPTY), Fmt() returns with no change to the StrBuf.

If the error has severity of info (E_INFO), the StrBuf is formatted.

If the error has any higher severity, the StrBuf argument passed to Fmt() is cleared and then replaced with the formatted error.

The opts argument is a flag or combination of flags defined by the ErrorFmtOpts enum. The default is EF_NEWLINE, which puts a newline at the end of the buffer.

Formatting options are as follows:

The following example code displays an error’s text, indented with a tab.

if ( e.Test() )
{
    StrBuf msg;
    e.Fmt( &msg, EF_INDENT );
    printf( "ERROR:\n%s", msg.Text() );
}

For more sophisticated handling, use a "switch" statement based on the error number to handle different errors in different ways.

The generic error codes are not documented at this time.

The following example attempts to establish a connection to a nonexistent server, and displays the resulting generic error code.

ClientApi client;
Error e;

client.SetPort( "bogus:12345" );
client.Init( &e );

if ( e.Test() ) printf( "Init() failed, error code %d.\n", e.GetGeneric() );

Executing the preceding code produces the following output:

Init() failed, error code 38.

The severity can take the following values:

The following code attempts to establish a connection to a server, and beeps if the severity is a warning or worse:

ClientApi client;
Error e;

client.SetPort( "magic:1666" );
client.Init( &e );

if ( e.GetSeverity() > E_INFO ) printf( "Uh-oh!%c\n", 13 );

This function returns nonzero if GetSeverity() == E_FATAL.

The following code attempts to establish a connection to a server, and beeps if the severity is fatal:

ClientApi client;
Error e;

client.SetPort( "magic:1666" );
client.Init( &e );

if ( e.IsFatal() ) printf( "Fatal error!%c\n", 13 );

This function returns nonzero if GetSeverity() == E_WARN.

The following code attempts to establish a connection to a server, and beeps if the severity is a warning:

ClientApi client;
Error e;

client.SetPort( "magic:1666" );
client.Init( &e );

if ( e.IsWarning() ) printf( "Warning!%c\n", 13 );

To use an Error object to track network-related errors, use Net(). Note that network communication with the Perforce server and related errors are already handled by lower levels of the client API.

The following example adds an error message, related to a failure to bind to a network interface, to an Error object.

e.Net( "bind", service.Text() );

The “<<” operator can be used to add text to an error as if the error is an output stream. This operator is typically used in the implementation of other Error methods.

Note that an Error consists of more than its text, it’s more useful to use Set() to establish a base Error and then add text into that, rather than merely adding text to an empty Error object.

The following example creates an Error using Set() and the << operator.

e.Set( E_WARN, "Warning, number " ) << myErrNum;

The “<<” operator can be used to add text to an error as if the error is an output stream. This operator is typically used in the implementation of other Error methods.

Note that an Error consists of more than its text, it’s more useful to use Set() to establish a base Error and then add text into that, rather than merely adding text to an empty Error object.

The following example creates an Error using Set() and the << operator.

e.Set( E_WARN, "Warning! " ) << "Something bad happened";

See Error::operator << (int) for details.

The “=” operator copies one Error into another.

The following example sets Error e1 to equal e2.

Error e1, e2;
e1 = e2;

An Error can hold multiple error messages; Set() adds the error message to the Error, rather than replacing the Error’s previous contents.

An ErrorSeverity is an int from 0-4 as described in the documentation on GetSeverity().

The following example adds a fatal error to an Error object.

Error e;
e.Set( E_FATAL, "Fatal error!");

See Error::Set( enum ErrSeverity, const char * ) for details.

An ErrorId is a struct containing an int (s) and a const char * (fmt).

To use an Error object to track errors generated by system calls such as file operations, use Sys().

The following example adds an error message, related to a failure to rename a file, to an Error object.

e.Sys( "rename", targetFile->Name() );

Test() returns nonzero if GetSeverity() != E_EMPTY.

The following code attempts to establish a connection to a server, and beeps if an error occurs:

ClientApi client;
Error e;

client.SetPort( "magic:1666" );
client.Init( &e );

if ( e.Test() ) printf( "An error has occurred.%c\n", 13 );

If the error is empty (severity is E_EMPTY), Abort() returns. Otherwise Abort() causes the program to exit with a status of -1.

Abort() is typically called after Init() or Run() to abort the program with a non-zero status if there has been a connection problem. The code in p4api.cc is one example:

ClientApi client;
Error e;

client.Init( &e );
ErrorLog::Abort();

If any errors are generated during ClientApi::Init(), the Error object is non-empty, and Abort() reports the connection error before terminating the program.