Helix Core Extensions Developer Guide (2019.1)

Class P4.P4

An interface to the Helix server client API. See Examples of server extensions.

Class methods

P4.P4:new -> P4.P4

Constructs a new P4.P4 object.

p4 = P4.P4:new()   

Instance Methods

p4.api_level= number -> number

Sets the API compatibility level desired. Using this method allows you to lock your script to the output format of an older Helix server release and facilitate seamless upgrades. This method, if called, should be called prior to calling p4:connect()

p4 = P4.P4:new()
p4.api_level = 86 # Lock to 2019.1 format
p4:connect()

For more information about the API levels, see the Support Knowledgebase article, "Helix Client Protocol Levels".

p4.api_level -> number

Returns the current Helix C/C++ API compatibility level. Each iteration of the Helix Core server is given a level number. As part of the initial communication, the client protocol level is passed between client application and the Helix Core server. This value, defined in the Helix C/C++ API, determines the communication protocol level that the Helix server client will understand. All subsequent responses from the Helix Core server can be tailored to meet the requirements of that client protocol level.

For more information, see "Helix Client Protocol Levels"

p4.charset= string -> string

Sets the character set to use when connecting to a Unicode-enabled server. Do not use when working with non-Unicode-enabled servers.

p4 = P4.P4:new()
p4.charset = "utf-8"
p4:connect()

p4.charset -> string

Get the name of the character set in use when working with Unicode-enabled servers.

p4.client= string

Set the name of the client workspace you wish to use. This method, if called, should be called prior to calling p4:connect()

p4 = P4.P4:new()
p4.client = "www"
p4:connect()

p4.client -> string

Get the name of the Helix server client currently in use.

p4 = P4.P4:new()
print( p4.client )

p4:connect() -> boolean

Connect to the Helix Core server. You must connect before you can execute commands.

p4 = P4.P4:new()
p4:connect()

p4:is_connected() -> boolean

Test whether or not the session is connected.

p4 = P4.P4:new()
p4:is_connected()

p4.cwd -> string

Get the current working directory for this server extension.

p4 = P4.P4:new()
print( p4.cwd )

p4:disconnect() -> boolean

Disconnect from the Helix Core server.

p4 = P4.P4:new()
p4:connect()
p4:disconnect()

p4.env(string) -> string

Get the value of a Helix server environment variable, taking into account P4CONFIG files and (on Windows and OS X) the registry or user preferences.

p4 = P4.P4:new()
print p4.env( "P4PORT" )

p4.errors -> table

Returns the table of errors which occurred during execution of the previous command.

p4.exception_level = number

Enables or disables the throwing of exceptions. The following two levels are supported:

  • 0 disables all exception raising and makes the interface completely procedural.
  • 1 causes exceptions to be raised for both errors and warnings. This is the default.

p4.exception_level -> number

Returns the current exception level.

If 0, exceptions are not used. When set to 1, exceptions are enabled.

p4.format_spec( "<spectype>", table ) -> string

Converts the fields in a table containing the elements of a Helix server form (spec) into the string representation familiar to users.

The first argument is the type of spec to format: for example, client, branch, label, and so on. The second argument is the table to convert to a string.

p4.graph= boolean

Enable or disable support for graph depots. You can enable or disable support for graph depots both before and after connecting to the server.

p4 = P4.P4:new()
p4.graph = false

p4.graph -> boolean

Returns whether or not support for Helix server graph depots is enabled.

p4 = P4.P4:new()
print( p4.graph )
p4.graph = false
print( p4.graph )

p4.host= string

Set the name of the current host. If not called, defaults to the value of P4HOST taken from any P4CONFIG file present, or from the environment as per the usual Helix server convention. This method, if called, should be called prior to calling p4:connect()

p4 = P4.P4:new()
p4.host = "workstation123.example.com"
p4:connect()

p4.host -> string

Get the current hostname.

p4 = P4.P4:new()
print( p4.host )

p4.input= ( string|table ) -> boolean

Store input for the next command.

Call this method prior to running a command requiring input from the user. When the command requests input, the specified data will be supplied to the command.

You may pass a string, or (for commands that take multiple inputs from the user) a table of strings. If you pass a table, note that the table will be shifted each time Helix server asks the user for input.

p4.messages -> table

Returns a table of P4.Message objects.

p4.p4config_file -> string

Get the path to the current P4CONFIG file.

p4 = P4.P4:new()
print( p4.p4config_file )

p4.parse_spec( "<spectype>", string ) -> table

Parses a Helix server form (spec) in text form into a table using the spec definition obtained from the server.

The first argument is the type of spec to parse: client, branch, label, and so on. The second argument is the string buffer to parse.

p4.password= string

Set your Helix server password or the ticket value to be used for this connection. If no password or ticket is given, it uses the value of P4PASSWD from any P4CONFIG file in effect, or from the environment according to the normal Helix server conventions.

p4 = P4.P4:new()
p4.password = "mypass"
p4:connect()

p4.password -> string

Get the current password or ticket. This may be the password in plain text, or if you’ve used P4#run_login(), it’ll be the value of the ticket you’ve been allocated by the server.

p4 = P4.P4:new()
print( p4.password )

p4.port= string

Set the host and port of the Helix server you want to connect to. If not used, the value defaults to the value of P4PORT in any P4CONFIG file in effect. If there is no such value, it defaults to the value of P4PORT taken from the environment.

p4 = P4.P4:new()
p4.port = "localhost:1666"
p4:connect()
...
p4.disconnect()

p4.port -> string

Get the value of the P4PORT of the current Helix server.

p4 = P4.P4:new()
print( p4.port )

p4.prog= string

Set the name of the script, as reported to Helix server system administrators.

p4 = P4.P4:new()
p4.prog = "sync-script"
p4:connect()
...
p4.disconnect()

p4.prog -> string

Get the name of the program as reported to the Helix server.

p4 = P4.P4:new()
p4.prog = "sync-script"
print( p4.prog )

p4:reset()

Reset messages, warnings, and errors from a previous run() call to its default value.

p4.run( command, [arguments…]​ ) -> table

Runs the specified Helix server command with the arguments supplied. The command arguments should be passed as quoted and comma-separated strings, with no leading space. For example:

p4.run("print","-o","test-print","-q","//depot/Jam/MAIN/src/expand.c")

The method returns a table of results whether the command succeeds or fails. The array table, however, be empty. Whether the elements of the table are strings or tables depends on (a) server support for tagged output for the command, and (b) whether tagged output was disabled by calling p4.tagged = false.

In the event of errors or warnings, and depending on the exception level in force at the time, the method will throw an exception. If the current exception level is below the threshold for the error/warning, the methods returns the output as normal and the caller must explicitly review errors() and warnings() to check for errors or warnings.

p4.server_level -> number

Returns the current Helix server level. Each iteration of the Helix server is given a level number. As part of the initial communication this value is passed between the client application and the Helix server. This value is used to determine the communication that the Helix server will understand. All subsequent requests can therefore be tailored to meet the requirements of this Server level.

For more information about the Helix server version levels, see the Support Knowledgebase article, "Helix server Version Levels".

p4.server_unicode -> boolean

Detects whether or not the server is in unicode mode.

p4.streams= boolean

Enable or disable support for streams. You can enable or disable support for streams both before and after connecting to the server.

p4 = P4.P4:new()
p4.streams = false

p4.streams -> boolean

Detects whether or not support for Helix server Streams is enabled.

p4 = P4.P4:new()
print ( p4.streams )
p4.streams = false
print ( p4.streams )

p4.tagged= boolean

Sets tagged output. By default, tagged output is on.

p4 = P4.P4:new()
p4.tagged = false

p4.tagged -> boolean

Detects whether or not you are in tagged mode.

p4 = P4.P4:new()
print ( p4.tagged )
p4.tagged = false
print ( p4.tagged )

p4.ticket_file = string

Sets the location of the P4TICKETS file.

p4 = P4.P4:new()
p4.ticket_file = "/home/bruno/tickets"

p4.ticket_file -> string

Get the path to the current P4TICKETS file.

p4 = P4.P4:new()
print( p4.ticket_file )

p4.track= -> boolean

Instruct the server to return messages containing performance tracking information. By default, server tracking is disabled.

p4 = P4.P4:new()
p4.track = true

p4.track -> boolean

Detects whether or not performance tracking is enabled.

p4 = P4.P4:new()
p4.track = true
print ( p4.track )
p4.track = false
print ( p4.track )

p4.user= string

Set the Helix server username. If not called, defaults to the value of P4USER taken from any P4CONFIG file present, or from the environment as per the usual Helix server convention. If used, should be called before connecting to the Helix server.

p4 = P4.P4:new()
p4.user = "bruno"
p4:connect()
...
p4:disconnect()

p4.user -> string

Returns the current Helix server username.

p4 = P4.P4:new()
print( p4.user )

p4.version= string

Set the version of your script, as reported to the Helix server.

p4.version -> string

Get the version of your script, as reported to the Helix server.

p4.warnings -> table

Returns a table of warnings that arose during execution of the last command.