Local and refer IPs

This training page demonstrates how to load workspaces in local or refer mode and how to switch IPs between local and refer mode from an existing workspace.

Local and refer mode

When loading an IP into a workspace, the user can bring in the IPs in either Local Mode or Refer Mode. Refer Mode IPs are read only, but will load very quickly if the IPV is already in the cache. Local Mode IPs can be modified, but may be noticeably slower to load if they are big enough.

Local mode

The IPs are loaded into the user's local workspace from the IP's DM system (Perforce in the case of this Training). The user can 'p4 edit' the files of the IP, make changes to them or add new files to the IP once it is in Local Mode. When loading the IP or checking the status of the workspace, the "Mode" column will indicate whether the IP is in Local or Refer Mode.

Viewing the Mode Column 
> pi ip load tutorial.gen_dig --local tutorial.gen_dig
Loading IPV 'tutorial.gen_dig@2.TRUNK' into Workspace '/tmp/tutorial.gen_dig'.
┌──────────────────┬─────────┬───────┬────────────────┐
│ NAME             │ VERSION │  MODE │ RELATIVE PATH  │
╞══════════════════╪═════════╪═══════╪════════════════╡
│ tutorial.gen_dig │ 2.TRUNK │ Local │ blocks/gen_dig │
└──────────────────┴─────────┴───────┴────────────────┘
> cd tutorial.gen_dig/
> ls
blocks  cds.lib  cds_run  workspace_cds.lib
> pi ws st -v
Workspace ID : 33f4e3d7-7cd1-4efb-bdcc-afcbbedb3ffd
Directory    : /tmp/tutorial.gen_dig
IP           : tutorial.gen_dig@2.TRUNK
Resources    :
┌──────────────────┬──────────────────┬───────────────┬───────────┬───────────────┬───────┐
│ NAME             │ EXPECTED VERSION │ LOCAL VERSION │ WS STATUS │ SERVER STATUS │  MODE │
╞══════════════════╪══════════════════╪═══════════════╪═══════════╪═══════════════╪═══════╡
│ tutorial.gen_dig │     2.TRUNK      │    2.TRUNK    │     OK    │       OK      │ Local │
└──────────────────┴──────────────────┴───────────────┴───────────┴───────────────┴───────┘
> ls -ltr ./blocks/
total 4
drwxr-x--- 5 mdx mdx 4096 Jun 19 11:14 gen_dig

 IPs can be switched between local and refer mode using the following commands from within the workspace: 

> pi ip refer <IP Name> 
OR
> pi ip refer --all

pi ip refer --all Comand 
> pi ip refer --all
Switching 'tutorial.gen_dig@2.TRUNK' to refer mode.
Successfully switched 'tutorial.gen_dig@2.TRUNK' to refer mode.
> pi ws st -v
Workspace ID : 33f4e3d7-7cd1-4efb-bdcc-afcbbedb3ffd
Directory    : /tmp/tutorial.gen_dig
IP           : tutorial.gen_dig@2.TRUNK
Resources    :
┌──────────────────┬──────────────────┬───────────────┬───────────┬───────────────┬───────┐
│ NAME             │ EXPECTED VERSION │ LOCAL VERSION │ WS STATUS │ SERVER STATUS │  MODE │
╞══════════════════╪══════════════════╪═══════════════╪═══════════╪═══════════════╪═══════╡
│ tutorial.gen_dig │     2.TRUNK      │    2.TRUNK    │     OK    │       OK      │ Refer │
└──────────────────┴──────────────────┴───────────────┴───────────┴───────────────┴───────┘
> ls -ltr ./blocks/
total 0
lrwxrwxrwx 1 mdx mdx 38 Jun 19 11:17 gen_dig -> /picache-root/tutorial/gen_dig/TRUNK/2

 To try the same exercise, however starting the IP from Refer Mode and switching it to Local Mode. Note that attempting to load the IP into the same workspace directory as the previous exercise ('/<Working Directory>/tutorial.gen_dig') will result into the following error since there can only be a single top level IP per workspace:

Switching to Refer Mode 
> pi ip load tutorial.gen_dig
ERROR:Workspace Error.
  The directory '/<Working Directory>/tutorial.gen_dig' already exists

Refer Mode

When an IP is loaded into a workspace in Refer Mode, the files and folders in that workspace are merely links to the PI replication area. If users wish to make changes to any of the files, they would first need to change the IP from Refer to Local Mode before they are able to do so. When loading the IP or checking the status of the workspace, the "Mode" column will indicate whether the IP is in Local or Refer Mode.

Loading an IP in Refer Mode 
> pi ip load tutorial.gen_dig tutorial.gen_dig_REFER
Loading IPV 'tutorial.gen_dig@2.TRUNK' into Workspace '/tmp/tutorial.gen_dig_REFER'.
┌──────────────────┬─────────┬───────┬────────────────┐
│ NAME             │ VERSION │  MODE │ RELATIVE PATH  │
╞══════════════════╪═════════╪═══════╪════════════════╡
│ tutorial.gen_dig │ 2.TRUNK │ Refer │ blocks/gen_dig │
└──────────────────┴─────────┴───────┴────────────────┘
> cd tutorial.gen_dig_REFER
> pi ws st -v
Workspace ID : addab813-e324-457a-9f6f-a368d4ee0eba
Directory    : /tmp/tutorial.gen_dig_REFER
IP           : tutorial.gen_dig@2.TRUNK
Resources    :
┌──────────────────┬──────────────────┬───────────────┬───────────┬───────────────┬───────┐
│ NAME             │ EXPECTED VERSION │ LOCAL VERSION │ WS STATUS │ SERVER STATUS │  MODE │
╞══════════════════╪══════════════════╪═══════════════╪═══════════╪═══════════════╪═══════╡
│ tutorial.gen_dig │     2.TRUNK      │    2.TRUNK    │     OK    │       OK      │ Refer │
└──────────────────┴──────────────────┴───────────────┴───────────┴───────────────┴───────┘
> ls -ltr ./blocks/
total 0
lrwxrwxrwx 1 mdx mdx 38 Jun 19 11:19 gen_dig -> /picache-root/tutorial/gen_dig/TRUNK/2

Note: that the output for 'ls -ltr' is the same as the output for the previous run. This occurs because both IPs are on Refer Mode, which results in 'gen_dig' linking to the same location in the PI replication area even though the IPs belong to different workspaces. 

 To change the workspace to Local Mode, run the following command from within the workspace:

> pi ip local <IP name>  
OR 
> pi ip local --all

Changing the Workspace to Local Mode 
> pi ip load tutorial.gen_dig tutorial.gen_dig_REFER
Loading IPV 'tutorial.gen_dig@2.TRUNK' into Workspace '/tmp/tutorial.gen_dig_REFER'.
┌──────────────────┬─────────┬───────┬────────────────┐
│ NAME             │ VERSION │  MODE │ RELATIVE PATH  │
╞══════════════════╪═════════╪═══════╪════════════════╡
│ tutorial.gen_dig │ 2.TRUNK │ Refer │ blocks/gen_dig │
└──────────────────┴─────────┴───────┴────────────────┘
> cd tutorial.gen_dig_REFER
> pi ws st -v
Workspace ID : addab813-e324-457a-9f6f-a368d4ee0eba
Directory    : /tmp/tutorial.gen_dig_REFER
IP           : tutorial.gen_dig@2.TRUNK
Resources    :
┌──────────────────┬──────────────────┬───────────────┬───────────┬───────────────┬───────┐
│ NAME             │ EXPECTED VERSION │ LOCAL VERSION │ WS STATUS │ SERVER STATUS │  MODE │
╞══════════════════╪══════════════════╪═══════════════╪═══════════╪═══════════════╪═══════╡
│ tutorial.gen_dig │     2.TRUNK      │    2.TRUNK    │     OK    │       OK      │ Refer │
└──────────────────┴──────────────────┴───────────────┴───────────┴───────────────┴───────┘
> ls -ltr ./blocks/
total 0
lrwxrwxrwx 1 mdx mdx 38 Jun 19 11:19 gen_dig -> /picache-root/tutorial/gen_dig/TRUNK/2