%Studio.SourceControl.ISC

This Parameter should be updated when synced from Perforce

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.

Add the specified classes to source control

Add the specified items to source control

Add the specified package(s) to source control

Called to add this item to source control

Inherited description: This is called after the UserAction() and after any template is run or dialog is displayed. For a 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 . If the Reload argument is set to true by this method then the current document will be reloaded in Studio.

Return filename of backup file of this item.

At the time of CheckOut(), a local backup of the item in its existing state is written 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.

Export the contents of a CSP directory

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).

Earlier versions of Ensemble physically copied files into newly created csp applications; these need to be enumerated so they can be skipped by BaselineExport()

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).

Check this routine/class/csp file into source control.

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.

Clears out a stored Perforce ticket which may be stored for the current user

Compiles InternalName if it still exists. Will skip up-to-date files.

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.

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 variables 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.

Utility Method to walk directory tree and find all files; returned array is keyed by the file minus the top directory and has a value of the full file

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)

Disconnect this document from source control

Returns value that shows whether or not this instance is "Disconnected" from Perforce.

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)

Takes a Source directory and reconciles it with a Target directory which is under source control:

• Files in Source which do not exist in Target will be copied into the Target and AddToSourceControl() will be called
• Files in Source which exist as Writeable in Target will be skipped
• Files in Source which exist as ReadWrite in Target will call Checkout() and then copied from Source to Target
• After all processing, files in Target which are Readonly will call RemoveFromSourceControl()

This will only run if the Namespace is in Permanently Disconnected Mode; for Connected clients, use the p4 reconcile feature in p4V

If IgnoreExtension is set then anything with that extension is excluded from reconciliation (e.g. .bak files left over from former local check-outs which didn't get cleaned up for some reason)

If the CCR is set then that value is set in the CCR column of the %Studio.SourceControl.Change table for this uncommitted change

Export System Default Settings and Add to Source Control or Check Out

Return filename of this item

Inherited description: 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.

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.

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 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

Inherited description: Get the latest version of this file from source control.

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 existence 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)

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.

Returns 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.

Takes a filename within the local Perforce workspace and returns a best guess as to the InternalName. If the file exists then the method 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 if it is a CCR enabled namespace it will return the path translated into the /itemsetsourcelink(_*) import/export format.

Unless IgnorePercent argument is set to 0, any %-items will 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 will not find matches for multi-tier mappings in ^Sources (e.g. ^Sources("HL7","*")="schema/hl7/", other than multi-tier mappings under /CSP/

Returns 1 if InternalName is excluded from source control

Inherited description: 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.

Inherited description: Returns true if this item is in source control and false otherwise.

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.

Indicates whether or not this instance is configured to accomodate multiple concurrent developers
It is considered a Shared development instance if one of the following is true:

• This is a Connected instance and there is a Shared Workspace defined for this instance or namespace
• This is a Permanently Disconnected Namespace (Permantently Disconnected means it is outside the InterSystems network and we always assume Shared)

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)

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.

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.

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.

Display connection information in the Output display

Return the name of this item without the prefix to be added by ExtName

Inherited description: Called after the compile of the item is done.

Inherited description: 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.

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.

Inherited description: This is called before the actual load of data to give the chance to load the item from an external format.

Called before the item is saved to the 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.

Inherited description: Called before Studio checks for the timestamp of an item.

Inherited description: 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.

** DEPRECATED - Use the more secure SecureP4Cmd(). Passed a 'p4' command, it runs it with '-ztag' and returns the parsed output

Readonly method which will show files marked for User Readonly as readonly even if process is running as root

Reconnect to the Perforce depot and mark all edited as edited.

Reconnect this document from source control

Called to delete this item from source control

** 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.

Passed a 'p4' by reference list of arguments in args, it runs 'p4' with '-ztag' and returns the parsed output

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.

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

Wrapper around %File:SetReadOnly to return a %Status

Wrapper around %File:SetWriteable to return a %Status

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.

Stores a Perforce ticket for future use by the current user

Inherited description: Undo the checkout of this item.

Unlock the source control hooks for this instance.

Update the ^Sources information with the file dates after a build

Inherited description: 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.

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.