System Administration: Editing Job Specifications

Perforce 98.2 p4 User's Guide


<< Previous Chapter Sys Admin: Protections	Table of Contents Index Perforce on the Web	Next Chapter >> Superuser Commands

Chapter 15
System Administration: Editing Job Specifications

Note

The Perforce user's use of p4 job is discussed elsewhere. This chapter covers superuser modification of the jobs system.

Perforce's default jobs system has five fields for tracking jobs. These fields may be sufficient for small-scale operations, but as the projects managed by Perforce grow, the information stored in these fields may be insufficient. The p4 jobspec command, which is available only to the Perforce superuser, can be used to add, delete, and change fields in the job template.

This chapter discusses the mechanics of altering the Perforce job format. Certain changes to the format are forbidden, others are permissible, but are not recommended. Recommendations and warnings about changes to job format are summarized at the end of this chapter.

The Default Perforce Job Format

A job created with the default Perforce job template has this format:


`# A Perforce Job Specification.` `#` `# Job: The job name. 'new' generates a sequenced job number.` `# Status: Either 'open', 'closed', or 'suspended'. Can be changed.` `# User: The user who created the job. Can be changed.` `# Date: The date this specification was last modified.` `# Description: Comments about the job. Required.` `Job: new` `Status: open` `User: rlo` `Date: 1998/06/03 23:16:43` `Description:` `<enter description here>`

The template that this job was created from can be viewed and edited with p4 jobspec. This command displays the following form:


`# A Perforce Job Specification.` `#` `# Updating this form can be dangerous!` `# See 'p4 help jobspec' for proper directions.` `Fields:` `101 Job word 32` `102 Status select 10` `103 User word 32` `104 Date date 20` `105 Description text 0` `Required:` `Job` `Status` `User` `Description` `Readonly:` `Date` `Comments:` `# A Perforce Job Specification.` `# Job: The job name. 'new' generates a sequenced job number.` # Status: `open', 'closed', or 'suspended'. Can be changed. `# User: The user who created the job. Can be changed.` `# Date: The date this specification was last modified.` `# Description: Comments about the job. Required.` `Values-Status: open/suspended/closed` `Default-Status: open` `Default-User: $user` `Default-Date: $now` `Default-Description: $blank`

It will be useful to refer to these examples while following the discussion below.

The Job Format's Fields

There are six fields and field types in the p4 jobspec form. These fields define the format of all Perforce jobs on your server. The fields and field types are:


Field / Field Type	Meaning
`Fields:`	A list of fields to be included in each job. Each field consists of an ID#, a name, a datatype, and a length.
`Required:`	A list of those fields in which values must be entered.
`Readonly:`	A list of fields whose default values can't be changed by the user. Each field in this list requires a corresponding `Default-`fieldname entry in the job specification.
`Values-fieldname:`	List of possible values for any `select` fields (defined below)
`Default-fieldname:`	A default value for field fieldname.
`Comments:`	The comments that will appear at the top of the `p4 job` form.

The `Fields:` Field

The p4 jobspec field Fields: lists the fields to be tracked by your jobs. The default Fields: field lists these fields:


`Fields:` `101 Job word 32` `102 Status select 10` `103 User word 32` `104 Date date 20` `105 Description text 0`

Each field must be listed on a separate line, and is comprised of four separate descriptors:


Field Descriptor	Meaning
`ID#`	A unique integer identifier by which this field is indexed. Once a field has been created and jobs have been entered into the system, the name of this field can change, but data will be inaccessible if the ID number changes. ID numbers must be between 101 and 199.
`Name`	The name of the field as it should appear on the `p4 job` form.
`Type`	One of five datatypes, described in the next table.
`Length`	The recommended size of the field's textbox as displayed in p4win, the Perforce GUI client. The value of this field has no effect on jobs edited from p4, and is not related to the actual length of the values stored in the depot.

The five field datatypes are:


Field Type	Explanation	Example
`word`	A single word	A user name: `edk`
`text`	A block of text that may span multiple lines	A job's description
`line`	One line of text	A user's real name: `Elizabeth Mitchell`
`select`	One of a set of values. Must have a corresponding `Values-`Fieldname:: field entered into the job specification	A job's status: `open/suspended/closed`
`date`	A date value	The date and time of job creation: `1998/07/15:13:21:46`

The `Fields:` Field: Caveats, Recommendations, and Warnings

Once a field has been created and jobs have been entered, do not change the field's ID#. Any data entered in that field through p4 job will be inaccessible.
Field names may be changed at any time. When changing a field's name, be sure to also change the fieldname in other p4 jobspec fields that reference this fieldname. For example, if you change the name of field 102 from status to jobstatus, this name must be changed in the p4 jobspec's Required: field.
Field ID# 101, the job's name, is required by Perforce and must not be deleted. As is true for all fields, its name may be changed.
Field ID# 102, the job's status, may be deleted; however, Perforce will be unable to update the status of jobs linked to particular changelists. If this field is present, Perforce will always set the value of this field to closed when a changelist containing this job is submitted, even if closed has been deleted from the list of possible values within the jobspec.
We recommend leaving the default fields 101 to 105 in the jobs system, using p4 jobspec only to add new fields to your jobs.

The `Default-fieldname:` Fields

Any field may be assigned a default value. The name of the field entered into the p4 jobspec form is Default-fieldname:, where fieldname is the name of the field whose default value is being assigned.

Any single-line string may be entered as a default value. Three variables are available for use as default values:


Variable	Value
`$user`	The Perforce user creating the job, as specified by the `P4USER` environment or registry variable, or as overridden with `p4 -u` username `job`.
`$now`	The date and time at the moment the job is saved.
`$blank`	The text `<enter description here>`

The Default-fieldname: fields and values for the standard jobs template are


`Default-Status: open` `Default-User: $user` `Default-Date: $now` `Default-Description: $blank`

The `Values-fieldname:` Fields

The set of possible values for any field of datatype select are provided in a Value-fieldname field. The values are entered on single line, separated by slashes.

In the default Perforce job specification, only the Status: field is a select field; its possible values have been set with


`Values-Status: open/suspended/closed`

The `Required:` Field

The Required: field lists those fields that must appear when jobs are created or updated. The default Required: field has these entries:


`Required:` `Job` `Status` `User` `Description`

If the user attempts to quit p4 job before values for these fields have been entered, they will be warned that the fields require a value. If they try to quit a second time without entering a value, changes to the job will be abandoned.

The `Readonly:` Field

The Readonly: field lists all job fields that are not allowed to be changed by the user. All the fields in this list must be given default values, as described above. The default Perforce job specification contains only one Readonly field:


`Readonly:` `Date`

The `Comments` Field

The Comments field supplies the comments that will appear at the top of the p4 job form. Since p4 job will not automatically tell your users the valid values of select fields, which fields are required, etc., it is important that your comments tell your users everything they need to know about each field.

Each line of the Comments: field must be indented by at least one tabstop from the left margin, and must begin with the comment character #. The comments for the default p4 job template appear in the job specification as


`Comments:` `# A Perforce Job Specification.` `#` `# Job: The job name. 'new' generates a sequenced job number.` # Status: `open', 'closed', or 'suspended'. Can be changed. `# User: The user who created the job. Can be changed.` `# Date: The date this specification was last modified.` `# Description: Comments about the job. Required.`

P4Win, the Perforce Windows GUI client, displays these comments in two ways:

When the P4Win user creates or edits a job and presses the Notes button in the job dialog box, a popup window displays the comments.
As the cursor moves over each field, the first line of the comment that correspond to that field is displayed in a ToolTip. P4Win constructs ToolTips by parsing the comments, looking for lines that start with a single word followed by a colon (:). The remainder of each of these lines is displayed as the ToolTip for the field that matches the first word of the line. Only the first line of the comment is displayed; thus, if P4Win encounters the jobspec comments above, the ToolTip for the Status: field will read
```
    Either 'open', 'closed', or 'suspended'.
```
Superusers of Perforce servers accessed by P4Win clients need to take extra care while writing comments.

Perforce's Own Altered Template

We designed our jobs system to meet our own evolving needs, and have modified our own job template accordingly. Our own internal job specification and the job form that it generates are provided here as a second example of the relationship between the p4 jobspec template and the p4 job format.


`# A Perforce Job Specification.` `#` `# Updating this form can be dangerous!` `# See 'p4 help jobspec' for proper directions.` `Fields:` `101 Job word 32` `106 Type select 10` `102 Status select 10` `108 Priority select 10` `107 Subsystem select 10` `109 Owned_By word 32` `103 Reported_By word 32` `104 Reported_Date date 20` `110 Modification_Date date 20` `112 Call_Numbers word 64` `111 Customers text 0` `105 Description text 0` `Required:` `Job` `Type` `Status` `Priority` `Subsystem` `Reported_By` `Description` `Readonly:` `Modification_Date` `Comments:` `# Perforce Jobs at Perforce:` `#` `# Job: Job number` `# Type: The type of the job. Acceptable values are` `# "bug", "sir", "problem" or "unknown"` `# Status: Has the job been fixed: Acceptable values are` `# "open", "closed", or "suspended"` `# Priority: How soon should this job be fixed?` `# Values are "a", "b", "c", or "unknown"` `# (This is NOT the same as severity!)` `# Subsystem: One of p4/gui/doc/mac/misc/unknown` `# Owned_by: Who's fixing the bug# Reported_by: Who reported the bug` `# Reported_date: When the bug was first entered` `# Mod_date: Last time the bug was updated` `# Call_Numbers: If from calltrack, the call numbers` `# Customers: Email addresses of customers, one per line` `# Description: Textual description of the bug` `Values-Type: bug/sir/problem/unknown` `Default-Type: unknown` `Values-Status: open/suspended/closed` `Default-Status: open` `Values-Priority: A/B/C/unknown` `Default-Priority: unknown` `Values-Subsystem: p4/gui/doc/mac/misc/unknown` `Default-Subsystem: unknown` `Default-Owned_By: unowned` `Default-Reported_By: $user` `Default-Reported_Date: $now` `Default-Modification_Date: $now` `Default-Call_Numbers: none` `Default-Customers: internal`

Running p4 jobspec at Perforce displays the following template:

And running p4 job at Perforce displays this job form:


`# Perforce Jobs at Perforce:` `#` `# Job: Job number` `# Type: The type of the job. Acceptable values are` `# "bug", "sir", "problem" or "unknown"` `# Status: Has the job been fixed: Acceptable values are` `# "open", "closed", or "suspended"` `# Priority: How soon should this job be fixed?` `# Values are "a", "b", "c", or "unknown"` `# (This is NOT the same as severity!)` `# Subsystem: One of p4/gui/doc/mac/misc/unknown` `# Owned_by: Who's fixing the bug` `# Reported_by: Who reported the bug` `# Reported_date: When the bug was first entered` `# Mod_date: Last time the bug was updated` `# Call_Numbers: If from calltrack, the call numbers` `# Customers: Email addresses of customers, one per line` `# Description: Textual description of the bug` `Job: new` `Type: unknown` `Status: open` `Priority: unknown` `Subsystem: unknown` `Owned_By: unowned` `Reported_By: rlo` `Reported_Date: 1998/06/04 02:13:10` `Modification_Date: 1998/06/04 02:13:10` `Call_Numbers: none` `Customers:` `internal` `Description:` `<enter description here>`

How Perforce Stores and Indexes Job Data

Perforce jobs are stored in three database tables: db.job, db.bodtext, and db.boddate. Although these tables contain the complete contents of all jobs, they do not contain the information required for fast searching with jobviews (discussed in Chapter 10). Thus, two additional tables have been created: db.ixtext and db.ixdate. The latter is an index of all dates in all jobs in chronological order; the former is an alphabetical index of all words in all non-date fields. Jobviews as used with p4 jobs -e and as specified in the p4 user form use these two tables for quick searching of all jobs.

Caveats, Warnings and Recommendations

! Warning !

Please read and understand the material in this section before attempting to edit a job specification!

Although the material in this section has already been presented elsewhere in this chapter, it is important enough to bear repeating. Please follow the guidelines presented here when editing job specifications with p4 jobspec.

Once a field has been created and jobs have been entered, do not change the field's ID#. Any data entered in that field through p4 job will be inaccessible.
Field names may be changed at any time. When changing a field's name, be sure to also change the fieldname in other p4 jobspec fields that reference this fieldname. For example, if you change the name of field 102 from status to jobstatus, this name must be changed in the p4 jobspec's Required: field.
Field ID# 101, the job's name, is required by Perforce and must not be deleted. As is true for all fields, its name may be changed.
Field ID# 102, the job's status, may be deleted; however, Perforce will be unable to update the status of jobs linked to particular changelists. If this field is present, Perforce will always set the value of this field to closed when a changelist containing this job is submitted, even if closed has been deleted from the list of possible values within the jobspec.
We recommend leaving the default fields 101 to 105 in the jobs system, using p4 jobspec only to add new fields to your jobs.
The comments that you write in the Comments: field are the only method provided by Perforce of letting your users know the requirements for each field. Please make these comments understandable and complete. These comments are treated specially in P4Win, the Perforce Windows GUI; for P4Win ToolTip compatability, make sure that the first line of the comment for each field can be read on its own.

Perforce 98.2 p4 User's Guide


<< Previous Chapter Sys Admin: Protections	Table of Contents Index Perforce on the Web	Next Chapter >> Superuser Commands

The Default Perforce Job Format

The Job Format's Fields

The Fields: Field

The Fields: Field: Caveats, Recommendations, and Warnings

The Default-fieldname: Fields

The Values-fieldname: Fields

The Required: Field

The Readonly: Field

The Comments Field