Home > Class Reference > ENSLIB namespace > %Studio.SourceControl.ISC
Private  Storage   


class %Studio.SourceControl.ISC extends %Studio.SourceControl.Base

This class is used internally by InterSystems. You should not make direct use of it within your applications. There is no guarantee made about either the behavior or future operation of this class.


Parameters Properties Methods Queries Indices ForeignKeys Triggers
2 66


IconStatus MainJob Modified StudioVersion Username

%AddToSaveSet %ClassIsLatestVersion %ClassName %ConstructClone
%DispatchClassMethod %DispatchGetModified %DispatchGetProperty %DispatchMethod
%DispatchSetModified %DispatchSetMultidimProperty %DispatchSetProperty %Extends
%GetParameter %IsA %IsModified %New
%NormalizeObject %ObjectModified %OnClose %OnNew
%OriginalNamespace %PackageName %RemoveFromSaveSet %SerializeObject
%SetModified %ValidateObject AddClassesToSourceControl AddItemsToSourceControl
AddPackagesToSourceControl AddToSourceControl AfterUserAction BackupName
BaselineCSPDir BaselineExport BaselineExportEnsembleExclude BaselineExportItem
CheckIn CheckIndexes CheckOut ClearPerforceTicket
DSCheckpointExport DefaultCredentialsDefined Disconnect DisconnectItem
Disconnected ExportCSPFile ExtName ExternalName
GeneratePerforceTicket GetCredentials GetLatest GetPortalPageOptions
GetSharedWorkspace GetStatus ImportCSPFile InstanceVersion
InternalNameFromExtName IsGenerated IsInSourceControl IsMapped
IsReadOnly IsSharedDevInstance IsTrakCare ItemIconState
JobUpdateSources Load Lock Locked
Login Logout Name OnAfterAllClassCompile
OnAfterClassCompile OnAfterCompile OnAfterDelete OnAfterLoad
OnAfterSave OnAfterStorage OnBeforeAllClassCompile OnBeforeClassCompile
OnBeforeCompile OnBeforeDelete OnBeforeLoad OnBeforeSave
OnBeforeTimestamp OnMenuItem OnPortalCreate P4Cmd
ReadOnly Reconnect ReconnectItem RemoveFromSourceControl
RunCmd SecureP4Cmd SecureRunCmd SetCredentials
SetSharedWorkspace StorePerforceTicket UndoCheckout Unlock
UpdateSources UserAction ValidatePerforceTicket


• parameter SrcVer = "$Id: //ce/2018.1.4/databases/sys/cls/Studio/SourceControl/ISC.xml#1 $";
This Parameter should be updated when synced from Perforce
• parameter Version = 165;
Revision number of this class when compiled as part of the //custom_ccrs/_common/config/... branch. This version will not be updated (by design) when the class is integrated to other branches. This allows the user to tell what version of the Studio client tools are in use.


• classmethod AddClassesToSourceControl(classes As %String) as %Status
Add the specified classes to source control
• classmethod AddItemsToSourceControl(ByRef items) as %Status
Add the specified items to source control
• classmethod AddPackagesToSourceControl(packages As %String) as %Status
Add the specified package(s) to source control
• method AddToSourceControl(InternalName As %String, Description As %String = "") as %Status
Called to add this item to source control
• method AfterUserAction(Type As %Integer, Name As %String, InternalName As %String, Answer As %Integer, Msg As %String = "", ByRef Reload As %Boolean) as %Status
This is called after the UserAction and after any template is run or dialog is displayed. For list of input arguments see UserAction In the case of the dialog the button pushed by the user is passed in Answer:
  • 0 - No
  • 1 - Yes
  • 2 - Cancel
For the dialog that contains a textbox field the text of this field is passed in 'Msg' argument. In the case of a template if the template was closed from the 'x' button then Answer=2 to indicate the user attempted to cancel the operation. Otherwise if the template closed normally by getting to the end Answer=1. For the cases where Studio did not perform any interaction this method is not called. The default implementation is to call the standard source control tags as Studio did in Cache 5.0. If the Reload argument is set to true by this method then the current document will be reloaded in Studio
• classmethod BackupName(InternalName As %String) as %String
Return filename of backup file of this item

At the time of CheckOut, a local backup of the item in its existing state is backed up to the file system with a .bak extension. This file will be used on Disconnected systems to restore to the previous state when UndoCheckout is called. It can also be used for diffs from the original file state.

• method BaselineCSPDir(dir As %String, appDir As %String, app As %String, ToReadOnly As %Boolean = 0, useEnsembleExclusionlist As %Boolean = 0)
Export the contents of a CSP directory
• classmethod BaselineExport(classesOnly As %Boolean = 0, interactive=1, targetDirectory=$get(^Sources), changeToReadonly As %Boolean = 1, includeMapped As %Boolean = {'$get(^SYS("SourceControl", "Misc", "LockMapped"))}) as %Status
This method exports all Classes, Routines, Include files, CSP Application files, and Projects files from a namespace into a file structure that can then be added to Source Control

This should be run from the terminal, and the user will be prompted as to whether they want to export to the current ^Sources location or an alternate location (alternate is recommended).

The method will then iterate through all Classes, Routines, Include files, CSP Application files and Projects and will export them to ^Sources based on the mappings in the ^Sources global.

NOTE - this does not export "Generated" classes

Passing classesOnly as '1' will export only the baseline of the classes. This is useful for exporting all updated XML after changing to a new class compiler version.

Pass interactive as 0 in order to call this programmatically

Pass targetDirectory to specify the directory for export (NOTE - this cannot equal ^Sources for TrakCare exports)

Pass boolean changeToReadOnly to control whether the files should be changed to read-only after export (defaults to true)

Pass boolean includeMapped to control whether items mapped from other databases should be included in the export (defaults to true) The default value for this argument will be the inverse of the source hooks LockMapped setting for this namespace (so if nothing is set, then Mapped will be included by default)

• method BaselineExportEnsembleExclude() as %String
Earlier versions of Ensemble physically copied files into newly created csp applications; these need to be enumerated so they can be skipped by BaselineExport()
• method BaselineExportItem(InternalName As %String, ToReadOnly As %Boolean = 0, CheckOut As %Boolean = 0, includeMapped As %Boolean = {'$get(^SYS("SourceControl", "Misc", "LockMapped"))}) as %Status
Exports a specific item
If ToReadOnly is true, then the files will be manually changed to ReadOnly afterwards (for use when exporting from LIVE and leaving items uneditable afterwards)
If CheckOut is true, then the Source Control CheckOut/AddToSourceControl logic is used If includeMapped is true, then items mapped from other DBs will be exported, otherwise they will be skipped. The default value for this argument will be the inverse of the source hooks LockMapped setting for this namespace (so if nothing is set, then Mapped will be included by default)
• method CheckIn(InternalName As %String, Description As %String) as %Status
Check this routine/class/csp file into source control.
• classmethod CheckIndexes()
• method CheckOut(InternalName As %String, Description As %String, Load As %Boolean = 1) as %Status
Check this routine/class/csp file out of source control.
Following successful checkout, the copy of the file on disk is loaded into the Namespace, unless Load is false.
• classmethod ClearPerforceTicket() as %Boolean
Clears out a stored Perforce ticket which may be stored for the current user
• classmethod DSCheckpointExport(ListOnly As %Boolean = 0, AddNew As %Boolean = 1, ExportAll As %Boolean = 0, Interactive As %Boolean = 1) as %Status
The initial implementation of DS II did not include source control hooks in the UI, so it is necessary to do check-out / export DSII classes and Folder Items just prior to submitting the changes to Perforce.
DSCheckpointExport() will check for the last time that DSCheckpointExport() was run, and will check out and export all changes DS II items since that timestamp. This should work for both Connected and Disconnected instances.
If ListOnly is true, then a list will be displayed but nothing will actually be checked out.
If AddNew is true, then all items which are not yet on disk in the local workspace will be marked for 'add' and exported, otherwise, only those already on disk will be exported.
If ExportAll is true, then the timestamp from the previous export will be ignored and all DeepSee work that is in Source Control will be checked out.
If Interactive is true, then the user will be prompted for their Perforce password if it is a Connected instance
• classmethod DefaultCredentialsDefined() as %Boolean
Method returns true if there are default perforce credentials defined, and false otherwise

NOTE - if there is no credentials data stored at all, the the assumption is made that this is a single-user system that relies on environment variable for Perforce access, and 'true' will be returned so that the user will not be prompted for credentials or told that none are defined. Credentials must be stored entirely in environment variables, or entirely in the DB for a given instance.

• classmethod Disconnect(Level As %Integer = 1) as %Status
Disconnect from Perforce depot

Values for 'Level' parameter are:

  • 1: Instance is Disconnected but could connect at a future time (default)
  • 2: Instance is Permanently Disconnected (no plans of ever connecting to Perforce)
• classmethod DisconnectItem(InternalName As %String) as %Status
Disconnect this document from source control
• classmethod Disconnected() as %Integer
Returns value that shows whether or not this instance is "Disconnected" from Studio

Return values are:

  • 0: Instance is Connected
  • 1: Instance is Disconnected but could connect at a future time
  • 2: Instance is Permanently Disconnected (no plans of ever connecting to Perforce)
• classmethod ExportCSPFile(InternalName As %String) as %Status
• classmethod ExtName(InternalName As %String) as %String
Return filename of this item
• method ExternalName(InternalName As %String) as %String
Convert the internal name, e.g. TEST.MAC to an external name that is used to export the routine/class/csp item. This is often a filename to write the file out to.
• classmethod GeneratePerforceTicket(p4pass As %String = "", ByRef p4ticket As %String) as %Status
This method will accept a Perforce password and will attempt to generate a Perforce ticket tied to this server for use within the hooks. In the process it will validate a ticket which may already be set, and if it is valid it will keep that ticket.
• classmethod GetCredentials(ByRef p4user As %String, ByRef p4passwd As %String, ByRef p4workspace As %String, ByRef p4dir As %String, ByRef p4port As %String) as %Boolean
Accessor method for accessing Perforce Credentials for current $USERNAME; returns false if no credentials were available
  • If there is a user-specific set of credentials defined for the current $USERNAME, these credentials will be returned
  • If a SharedWorkspace has been defined but there are no credentials for the current $USERSAME, then $USERNAME is returned as p4user assuming it's not a shipped Caché username
  • If a SharedWorkspace has been defined, then it will be returned in the p4workspace parameter; otherwise the workspace for the credential set will be returned
  • If credentials exist for this specific $USERNAME, then p4passwd is returned from the the current studio process (the password stored in credentials is ignored)
  • If there is no data at all in ^%SYS("SourceControl","Credentials"), then the method returns 'true', assuming the Environment variables are used to store the credentials
• method GetLatest(InternalName As %String) as %Status
Get the latest version of this file from source control.
• classmethod GetSharedWorkspace(ByRef p4workspace As %String, ByRef p4directory As %String) as %Boolean
Accessor method to get the Perforce Shared Workspace if it is defined; if it is not defined, the method returns false. If this method returns false, then the assumption should be made that this is a single-developer instance (not shared by multiple developers).

The method will check for the existance of a namespace-specific workspace, and will use that if it exists. If a namespace specific workspace is not defined, then it will look for an instance-wide Shared Workspace.

This also allows a user to retrieve the stored alternate workspace directory root (-d flag in P4)

• method GetStatus(InternalName As %String, ByRef IsInSourceControl As %Boolean, ByRef Editable As %Boolean, ByRef IsCheckedOut As %Boolean, ByRef UserCheckedOut As %String) as %Status
Return information about this entity

This method checks the current status of the item, seeing whether or not it is in source control (based on an exported copy of the item on disk), and if it is in source control, whether it is currently checked out (based on whether the file is Readonly or not).

If the file is checked out, this method will check to find the value of $USERNAME for whomever performed CheckOut. If the current $USERNAME does not match, then the user will not be permitted to edit the file as it has been checked out by another user

• classmethod ImportCSPFile(InternalName As %String) as %Status
• classmethod InstanceVersion() as %Numeric
Returns value the Major.Minor version for this instance, so it can be used in comparison code which makes sure certain features are used in appropriate versions
• classmethod InternalNameFromExtName(ExtName, IgnorePercent=1, IgnoreNonexistent=1) as %String
Takes a filename within the local Perforce workspace and returns a best guess as to the InternalName. If the file exists then Caché will attempt to open it to find the item name. If it does not exist (or if it can't open it) then it will try to determine the item name based on the location in directory tree and the structure of the mappings in ^Sources.

If no item in the database can be found to map to the external filename, then "" will be returned by the method.

Unless IgnorePercent argument is set to 0, any %-items to return ""

Unless IgnoreNonexistent argument is set to 0, if the item isn't found in the database, then "" will be returned

Known Limitations (if the physical file doesn't exist):

  • Due to this historical act of stripping '%' from the beginning of package names, if there exists both a %-item and a non-%-item which map to the same location, then "" will be returned as the result is indeterminate without having access to the source file.
  • The method currently does not return internal names for CSP files that don't exist as source on the file system
  • The method currently will not find matches for multi-tier mappings in ^Sources (e.g. ^Sources("HL7","*")="schema/hl7/")
• classmethod IsGenerated(InternalName As %String) as %String
Return 1 if you wish this item to appear as if it is 'generated' when opened in Studio, return 0 to force this item not to appear as 'generated' and return "" to use normal processing
• method IsInSourceControl(InternalName As %String) as %Boolean
Returns true if this item is in source control and false otherwise.
• classmethod IsMapped(name As %String, ByRef sourcedb As %String)
Return true if this item is mapped from a database other than the default routine database. Also return the source database in sourcedb.

NOTE: This is available as %RoutineMgr::IsMapped() in 2013.1 and later; it is included in this class to support the source hooks working on earlier versions

• classmethod IsSharedDevInstance() as %Boolean
Indicates whether or not this instance is configured to accomodate multiple concurrent developers
• classmethod IsTrakCare() as %Boolean
Returns true if this namespace is a TrakCare namespace (note - this will also catch a HealthShare VIEWERLIB, but we shouldn't be changing any data in there anyway)
• classmethod JobUpdateSources() as %String
Job off a background job to update the sources information. It returns -1 if it could not start the job or the $job number if successful
• classmethod Load(InternalName As %String, display As %Boolean = 1) as %Status
• classmethod Lock(Admin As %Boolean = 0) as %Status
Lock the source control hooks for this instance.

The default setting will be "Locked". Passing a '1' for the Admin parameter will set the instance to AdminLocked.

See Locked for more details.

• classmethod Locked() as %String
Returns value that shows whether or not this instance is "Locked"

Return values are:

  • "": Instance has never been Locked or Unlocked (default)
  • 0: Instance is Unlocked
  • 1: Instance is Locked
  • 2: Instance is AdminLocked

When the instance is Locked or AdminLocked, no changes can be made via Studio. It is possible to change from Locked to NotLocked via different UIs. When an instance is AdminLocked it should only be possible to unlock it via the Unlock method.

• method Login(Name As %String, Password As %String) as %Status
Display connection information in the Output display
• classmethod Name(InternalName As %String) as %String
Return the name of this item without the prefix to be added by ExtName
• method OnAfterCompile(InternalName As %String) as %Status
Called after the compile of the item is done.
• method OnAfterSave(InternalName As %String, Object As %RegisteredObject) as %Status
This is called after the item has been saved to the database. It may be passed a reference to the object representing the item just saved. It can be use to export this documement to an external form for example.
• method OnAfterStorage(InternalName As %String, Location As %String = "") as %Status
Called if compilation of the class has modified the storage (or another part of the class) so we need to write out the new version and if the file is not already checked out we need to check it out automatically.
• method OnBeforeLoad(InternalName As %String, display As %Boolean = 1) as %Status
This is called before the actual load of data to give the chance to load the item from an external format.
• method OnBeforeSave(InternalName As %String, Location As %String = "", Object As %RegisteredObject = $$$NULLOREF) as %Status
Called before the item is saved to the Cache database it is passed a reference to the current temporary storage of this item so that it can be modified before the save completes. If you quit with an error value then it will abort the save.
• method OnBeforeTimestamp(InternalName As %String)
Called before Studio checks for the timestamp of an item.
• method OnMenuItem(MenuName As %String, InternalName As %String, SelectedText As %String, ByRef Enabled As %Boolean, ByRef DisplayName As %String) as %Status
This is called for every menu item returned to Studio to allow the menu to be enabled/disabled without having to write a custom query for MenuItems. The DisplayName of this menu is also passed by reference and this may be modified to change the appearance of this menu item. The MenuName is the main menu name then the submenu name separated by a ','. If Enabled is set to -1 then it will remove this menu item from the list totally, 0 will gray the menu item out and the default 1 will display the menu item as normal.
• classmethod P4Cmd(cmd As %String, Output output As %String) as %Status
** DEPRECATED - Use the more secure SecureP4Cmd. Passed a 'p4' command, it runs it with '-ztag' and returns the parsed output
• classmethod ReadOnly(filename) as %Boolean
Readonly method which will show files marked for User Readonly as readonly even if process is running as root
• classmethod Reconnect() as %Status
Reconnect to the Perforce depot and mark all edited as edited.
• classmethod ReconnectItem(InternalName As %String) as %Status
Reconnect this document from source control
• method RemoveFromSourceControl(InternalName As %String, Description As %String = "") as %Status
Called to delete this item from source control
• classmethod RunCmd(cmd As %String, ByRef output As %String, display As %Boolean = 1, stream As %Boolean = 0) as %Status
** DEPRECATED - Use more secure SecureRunCmd instead

Run a shell command and report any error message, return output with lines as subscripts of the array if stream is false (the default) but if stream is true then we will return the output as a stream to be read by the caller.

• classmethod SecureP4Cmd(ByRef args, Output output As %String) as %Status
Passed a 'p4' by reference list of arguments in args, it runs 'p4' with '-ztag' and returns the parsed output
• classmethod SecureRunCmd(cmd As %String, ByRef args, ByRef output As %String, display As %Boolean = 1, stream As %Boolean = 0, input As %String = "") as %Status
Run a command and report any error message, return output with lines as subscripts of the array if stream is false (the default) but if stream is true then we will return the output as a stream to be read by the caller. Passed the executable name in cmd and the list of arguments as an integer subscripted local array passed in by reference in args.
• classmethod SetCredentials(p4user As %String = "", p4passwd As %String = "", p4workspace As %String = "", p4dir As %String = "", p4port As %String = "") as %Boolean
Accessor method for setting Perforce Credentials, returns false if credentials could not be set
  • If p4user is passed as a string, then it (along with the other arguments) will be the default for this instance
  • If p4user is of the form $LB(cacheUser, p4user), then p4user only be used when $USERNAME=cacheUser, and all other arguments will be ignored. The workspace details should be set via SetSharedWorkspace(), and the user will be prompted for the p4passwd value at runtime
  • If p4user is "" , then the default credentials will be cleared
  • If p4user is of the form $LB(cacheUser,""), then the perforce username for cacheUser will be cleared
• classmethod SetSharedWorkspace(p4workspace As %String = "", p4directory As %String = "", namespace As %String = "") as %Boolean
Accessor method for setting Perforce Shared Workspace; returns false if credentials could not be set

If the namespace argument is not passed, then the values will be set for the entire instance. If it is passed, then the workspace and alternate workspaace directory root will be used just for that specified workspace.

This also allows a user to set the alternate workspace directory root (-d flag in P4)

Important Note: Passing p4workspace as "" will clear out all of the shared worspace settings, and will merge them into ^%SYS("SourceControl","PriorSharedWorkspace") for future reference.

• classmethod StorePerforceTicket(ticket As %String = "") as %Boolean
Stores a Perforce ticket for future use by the current user
• method UndoCheckout(InternalName As %String) as %Status
Undo the checkout of this item.
• classmethod Unlock() as %Status
Unlock the source control hooks for this instance.
• classmethod UpdateSources() as %Status
Update the ^Sources information with the file dates after a build
• method UserAction(Type As %Integer, Name As %String, InternalName As %String, SelectedText As %String, ByRef Action As %String, ByRef Target As %String, ByRef Msg As %String, ByRef Reload As %Boolean) as %Status
This is called when the user performs an action that may need to interact with the server, such as selecting a menu or adding a new document. This encompases what the deprecated Flags parameter did and allows additional flexibility.

The Type argument values are:

  • 0 : Server defined menu item selected
  • 1 : Other Studio action
When a menu item is selected the Name argument is the name of this menu item in the format '<MainMenu>,<SubMenu>'. For other Studio actions the Name argument is one of:
  • 0 : User has tried to change a document that is locked in source control
  • 1 : User has created a new document
  • 2 : User has deleted a document
  • 3 : User has opened a document
  • 4 : User has closed a document
  • 5 : User has connected to a new namespace
  • 6 : User has selected to import comma delimetered list of documents
  • 7 : User has saved a new document for the first time
  • The InternalName argument is the name of the document about which this action occurs. If there is any selected text in the document which has focus this is sent in the SelectedText argument. The Action argument is set by this method to tell Studio what to do. Possible return values for this are:
    • 0 : Do nothing, note that this method can still perform some action such as check an item out of source control, but Studio will not ask for user input.
    • 1 : Display the default Studio dialog with a yes/no/cancel button. The text for this dialog is provided in the 'Target' return argument.
    • 2 - Run a CSP page/Template. The Target is the full url to the CSP page/Template, as usual the page will be passed the current document name, any selected text, the project name, the namespace.
    • 3 - Run an EXE on the client. The Target is the name of an executable file on the client machine. It is the responsibility of the customer to ensure this EXE is installed in a suitable location.
    • 4 - Insert the text in Target in the current document at the current selection point
    • 5 - Studio will open the documents listed in Target, if there are multiple documents to open they will be separated with commas. If the document name is 'test.mac:label+10' it will open the document 'test.mac' and goto 'label+10'.
    • 6 - Display an alert dialog in Studio with the text from the Target variable
    • 7 - Display a dialog with a textbox and Yes/No/Cancel buttons. The text for this dialog is provided by the 'Target' return argument. The initial text for the textbox is provided by the 'Msg' return argument.
    If the Reload argument is set to true then the current document will be reloaded in Studio, this is useful if you change the document to change its attribute so Studio will pick up these changes.
    • classmethod ValidatePerforceTicket(ByRef timeRemaining As %String) as %Status
    Validate a ticket and return the amount of time remaining for that ticket. If the ticket is not valid it will clear it from the credential store since it is of no use