Class %Library.Routine

stream class %Library.Routine extends %CharacterStream, %AbstractStream

The %Routine class provides a way to create and manipulate routines stored within the Caché database.

The %Routine class provides a stream interface (see %AbstractStream) that allows you to read existing routines as well as create new one programmatically.

%Routine includes methods to save and compile modified routines.

For example, the following code creates, saves, and compiles a simple Caché routine (note that lines of code start with a space character):

	Set routine = ##class(%Routine).%New("MyRoutine.MAC")
	; Write lines of code to the routine
	Do routine.WriteLine("MyRoutine")
	Do routine.WriteLine("Tag()")
	Do routine.WriteLine(" Write ""This is my routine"",!")
	Do routine.WriteLine(" Quit")
	; save the routine
	Do routine.Save()
	; compile the routine
	Do routine.Compile()

Inventory

Parameters	Properties	Methods	Queries	Indices	ForeignKeys	Triggers
	18	62	4

Summary

Properties
%Location	AtEnd	Attributes	Generated	Id
IsModified	LanguageMode	LastModified	LineTerminator	Locked
Name	Namespace	RoutineName	RoutineType	RoutineVersion
Size	TimeStamp

Methods
%%OIDGet	%AddToSaveSet	%CheckUnique	%ClassIsLatestVersion
%ClassName	%ConstructClone	%Delete	%DeleteExtent
%DeleteId	%DispatchClassMethod	%DispatchGetModified	%DispatchGetProperty
%DispatchMethod	%DispatchSetModified	%DispatchSetMultidimProperty	%DispatchSetProperty
%Exists	%ExistsId	%Extends	%GetParameter
%GetSwizzleObject	%Id	%IsA	%IsModified
%KillExtent	%LocationSet	%LockStream	%New
%NormalizeObject	%ObjectModified	%Oid	%Open
%OpenId	%OriginalNamespace	%PackageName	%ReleaseLock
%Reload	%RemoveFromSaveSet	%RollBack	%Save
%SerializeObject	%SetModified	%UnlockStream	%ValidateObject
CheckProtect	CheckSyntax	Clear	CompareClose
CompareExecute	CompareFetch	Compile	CompileAll
CompileAllNamespaces	CopyFrom	CopyFromAndSave	Delete
DeleteAttribute	DeleteStream	Exists	FindAt
FindClose	FindExecute	FindFetch	Flush
GetAttribute	GetCurrentTimeStamp	GetDate	GetObjectVersion
GetStreamId	InputFromDevice	IsCharacter	IsDefinedAttribute
IsNull	LanguageModeGet	LanguageModeSet	LastModifiedGet
LineTerminatorGet	LineTerminatorSet	Lock	LockRoutine
MoveTo	MoveToEnd	NameGet	NamespaceGet
NextAttribute	OpenStream	OutputToDevice	OutputToDeviceAt
Read	ReadLine	ReadLineIntoStream	ReadSQL
Rewind	RoutineExists	RoutineListClose	RoutineListExecute
RoutineListFetch	RoutineListFetchRows	RoutineNameSet	RoutinesSortByFieldClose
RoutinesSortByFieldExecute	RoutinesSortByFieldFetch	RoutinesSortByFieldFetchRows	Save
SaveStream	SerializeToSyncSet	SetAttribute	SizeGet
StreamOIDIsNull	SyncStreamIn	Unlock	Write
WriteLine

Properties

• property Generated as %Boolean;

True if this routine is generated from something else

• property IsModified as %Boolean [ InitialExpression = 0 ];

• property LanguageMode as %Integer [ Calculated ];

The language mode of this routine

• property Locked as %Integer [ InitialExpression = 0 ];

Number of times this routines has been locked.

• property Name as %String [ Calculated ];

The name (without extension) of the routine associated with this object.
This is for backwards compatability only.

• property Namespace as %String [ Calculated ];

Return the namespace this routine is from

• property RoutineName as %String;

The name of the routine.

• property RoutineType as %String;

The type of the routine.

• property RoutineVersion as %Integer;

• property TimeStamp as %TimeStamp;

Methods

• classmethod %ExistsId(id As %String) as %Boolean

Checks to see if the object identified by the ID id exists in the extent.
Returns %Boolean TRUE is it exists, FALSE if it does not.

• method %IsModified() as %Integer

Returns true (1) if a property of this instance has been modified, otherwise false (0). A TRUE result does not necessarily mean that any property has actually been changed. If %IsModified() returns false then the object has not been modified. There are some situations where we simply cannot efficiently detect a change in value. In these cases we will set the modified status of the property.

• method %ObjectModified() as %Integer

This method is somewhat similar to %IsModified but it also checks to see if swizzled references would cause the object to become modified should they be serialized. This works on the assumption that a reference to a persistent object will never be modified if the ID has already been assigned. For references to serial objects, a call to %ObjectModified indicates whether or not the serialized value is different. If the reference to a swizzled object is different from the initial object state then the $$$objModAll macro will already return true. Reference the Set code. Returns true (1) if this instance has been modified, otherwise false (0).

• classmethod CheckProtect(name As %String) as %Boolean

Check if we are allowed to save this routine in this namespace

• classmethod CheckSyntax(ByRef Source As %String, ByRef Errors As %String, LanguageMode As %Integer = 0) as %Status

This function syntax checks INT source code.
Source - source (INT) code; either a single line stored in a variable, or an array where: array(0)=#lines, array(1-n)=source
Errors (byref) - Returned array of errors detected by compiler
LanguageMode - language mode, 0-10 (optional, default 0)

• method Clear() as %Status

Clear the contents of this Stream from permanent storage. This will remove the permanent stream storage and any temporary stream and initialise the stream to its initial state that it starts in, including removing all the stream attributes.
Returns a %Status value indicating success or failure.

• method Compile(qspec As %String) as %Status

Compile this routine. The qspec is the standard objects qualifiers described in 'Do $system.OBJ.ShowQualifiers()'.

• classmethod CompileAll(Flags As %String = 0, IO As %String = $p, ByRef Count As %Integer, ByRef Errors As %Integer) as %Status

Compile all routines in a namespace.
This method will compile all routines in the current namespace.
Flags Bit string of options to method.
Bit 0 - Suppress syntax error display.
Bit 1 - Suppress output to principal device.
IO Already open device to send the output to. For example, "c:\a.out"
Count (by ref) Number of routines compiled.
Errors (by ref) Number of routines with syntax errors.

• classmethod CompileAllNamespaces(Flags As %String = 0, IO As %String = $p, ByRef Count As %Integer, ByRef Errors As %Integer) as %Status

Compile all routines in all namespace.
This method will compile all routines in all namespaces. This will not compile routines in SYSTEM defined namespaces.
Flags Bit string of options to method.
Bit 0 - Suppress syntax error display.
Bit 1 - Suppress output to principal device.
IO Already open device to send the output to. For example, "c:\a.out"
Count (by ref) Number of routines compiled.
Errors (by ref) Number of routines with syntax errors.

• classmethod Delete(rtnname As %String, flag As %String = 0, supressbackup As %Boolean = 0, nsp As %String = $zutil(5)) as %Status

Delete the routine rtnname. The parameter flag specifies now much to delete. The options are:

0 - Delete entire routine, for a MAC routine this will delete MAC, INT, OBJ. For an INT routine it will delete INT and OBJ, for a INC routine it will only delete the INC, for a BAS routine it will delete the BAS and the OBJ code.

1 - Delete just the named routine, for example for a MAC routine it will only delete the MAC and it will leave the INT and OBJ if present.

2 - Delete all the source code but leave any OBJ code.
This returns a %Status code to show if it worked or not. If you pass a name like 'test.mac;*' it will delete all backup versions of this routine. If the routine name which is passed does not exists, the method will return success.

• classmethod DeleteStream(sid As %ObjectIdentity) as %Status

Deprecated method, use %Delete instead. Deletes the stored stream identified by oid. This will not remove the stream attributes of any saved streams, it will just remove the stream data. If you need to clear the attributes as well you will have to call Clear on the stream object.

• classmethod Exists(name As %String) as %Boolean

This is a class method which tests if the routine name exists.
If name consists of a routine name and an extension, such as INT, MAC, etc. then it will check for this specific routine. If it just contains the routine name it will check if either MAC, INT, or BAS exists.
	Write ##class(%Routine).Exists("Test.MAC")
	Write ##class(%Routine).Exists("Test")

• method Flush() as %Status

Flush any output in the stream not already saved.

• method GetCurrentTimeStamp() as %TimeStamp

Get the on-disk timestamp for the routine.

• classmethod GetDate(name As %String) as %TimeStamp

Return the timestamp the routine with name was last updated.

• method GetObjectVersion() as %Numeric

Returns the major.minor version number of the Caché compiler that produced the object code for this routine. Returns 0 if there is no object code for the routine.

• method LanguageModeGet() as %Integer

This is a Get accessor method for the LanguageMode property.

• method LanguageModeSet(languagemode As %Integer) as %Status

This is a Set accessor method for the LanguageMode property.

• method LastModifiedGet() as %TimeStamp

This is a Get accessor method for the LastModified property.

• method LineTerminatorGet() as %String

This is a Get accessor method for the LineTerminator property.

• method Lock() as %Status

Lock the current routine

• classmethod LockRoutine(name As %String, lock As %Boolean = 1, nsp As %String = $namespace, IModeLock As %Boolean = 0) as %Status

Lock a particular routine name. If lock is true (the default) then it locks the routine, and if false then it unlocks the routine. If a routine is derived from a class then it will lock the class name in ^oddDEF to prevent another user from attempting to edit the class at the same time this process is editing the routine. If IModeLock is True, then it will unlock the routine with the #I flag so that the node will unlock even if in a transaction.

• method MoveToEnd() as %Status

Move to the end of the stream so the next Write will be appended to the end. This allows you to read from a stream, then MoveToEnd() and append new data, where just calling Write after a read will clear the stream before writing new data.
Returns a %Status value indicating success or failure.

• method NameGet() as %String

This is a Get accessor method for the Name property.

• method NamespaceGet() as %String

This is a Get accessor method for the Namespace property.

• method OpenStream(sid As %String) as %Status

• method Read(ByRef len As %Integer = 32000, ByRef sc As %Status) as %String

Reads up to len characters from the current position in the stream. The current position is advanced by the number of characters read. Upon exit, len is set to the actual number of characters read. If a read occurs when the stream position is at the end of the stream, len will be set to -1 and Read will return a null string ("").
You must call Rewind if you want to read a stream from the beginning again. Calling Read after Write implicitly ends the Write operation and rewinds to the start of the stream.
Returns a string up to len characters long. The byref argument sc will return a %Status if any error occurred during the read.

• method ReadLine(ByRef len As %Integer = 32000, ByRef sc As %Status, ByRef eol As %Boolean) as %String

Read a line from the stream. This will look for the line terminator in the stream and once it finds the terminator it will return the string minus the terminator character/s. If it reaches the end of the stream before it finds a terminator it will return the data it has so far, and if you specify a maximum size in len it will only read up to this number of characters. On exit len will contain the actual number of characters read. The byref argument sc will return a %Status if any error occured during the read and the byref argument eol is true if it found the line terminator and false otherwise. So for example you can read in a stream a line at a time and output the results to the current device with:
	While 'stream.AtEnd { Write stream.ReadLine(,.sc,.eol) If $$$ISERR(sc) { Write "ERROR" Quit } If eol { Write ! } }

• method Rewind() as %Status

Go back to the start of the stream.

• method RoutineExists() as %Boolean

This is an instance method which tests if this routine exists (that is, it has been saved to disk).

• classmethod RoutineListClose(QHandle As %Binary) as %Status

• final classmethod RoutineListExecute(ByRef QHandle As %Binary, ByRef spec As %String(MAXLEN=512)="", Dir As %Integer = 1, Type As %Integer = 0, Nsp As %String = $zu(5)) as %Status

• classmethod RoutineListFetch(ByRef QHandle As %Binary, ByRef Row As %List, ByRef AtEnd As %Integer = 0) as %Status

Fetch returns the next row in the query.

• classmethod RoutineListFetchRows(ByRef QHandle As %Binary, FetchCount As %Integer = 0, ByRef RowSet As %List, ByRef ReturnCount As %Integer, ByRef AtEnd As %Integer) as %Status

RoutineListFetchRows returns the next FetchCount rows in the query.

• method RoutineNameSet(newvalue As %String) as %Status

This is a Set accessor method for the RoutineName property.

• classmethod RoutinesSortByFieldClose(QHandle As %Binary) as %Status

• final classmethod RoutinesSortByFieldExecute(ByRef QHandle As %Binary, ByRef Spec As %String(MAXLEN=512)="", Dir As %Integer = 1, Type As %Integer = 0, OrderBy As %String = "Date", Nsp As %String = $zu(5)) as %Status

• classmethod RoutinesSortByFieldFetch(ByRef QHandle As %Binary, ByRef Row As %List, ByRef AtEnd As %Integer = 0) as %Status

Fetch returns the next row in the query.

• classmethod RoutinesSortByFieldFetchRows(ByRef QHandle As %Binary, FetchCount As %Integer = 0, ByRef RowSet As %List, ByRef ReturnCount As %Integer, ByRef AtEnd As %Integer) as %Status

RoutineListFetchRows returns the next FetchCount rows in the query.

• method Save(supressbackup As %Boolean = 0) as %Status

Save this routine.

• method SaveStream(supressbackup As %Boolean = 0, Output Refresh As %Boolean) as %Status

Deprecated method, use %Save instead. Saves the temporary copy of the stream data to a persistent location. Note that any locking or transaction handling must be done by the caller.
Returns a %Status value indicating success or failure.

• method SizeGet() as %Integer

Return the current size of the data stream.

• method Unlock() as %Status

Unlock the current routine

• method Write(data As %CacheString = "") as %Status

Appends the string data to the stream and advances the current stream position by the number of characters in data.
Note that a write operation immediately following a read or rewind will clear out the existing data in the stream.
Returns a %Status value indicating success or failure.

• method WriteLine(data As %String = "") as %Status

Appends the string data along with a line terminator to the stream and advances the current stream position by the number of characters in data plus the line terminator.
Returns a %Status value indicating success or failure.

Queries

• query Compare(Nsp1 As %String, RouName1 As %String, Nsp2 As %String, RouName2 As %String)

Selects LineNo1 As %String, Line1 As %String, LineNo2 As %String, Line2 As %String

This query provides a list of all lines that differ between two given routines.
Nsp1 and RouName1 specify the first routine.
Nsp2 and RouName2 specify the second routine.
Nsp1 and RouName2 can be either an explicit or an implied namespace.

• query Find(Namespace As %String, RoutineName As %String, FindWhat As %String, MatchCase As %Boolean = 1)

Selects Line As %String, Match As %Boolean

The query returns the routine that contains FindWhat, one line per row, with two columns, Line and Match. Line is the line text. Match is 1 if Line contains FindWhat. The entire routine is returned.

• query RoutineList(spec As %String(MAXLEN=512), dir As %Integer, type As %Integer, nsp As %String)

Selects Name As %String(MAXLEN=512) As FileName/Ext, Size As %Integer, Date As %TimeStamp, Lang As %String

This query provides a list of all routines that match the pattern specified by spec.
spec may contain both * and ? as wildcards. It may also consist of more than one, comma-delimited selections. For example:
"*.MAC"
"A*.MAC"
"A?.MAC"
"A*.MAC,B*.MAC"
dir specifies the direction to search in, 1 is forwards and -1 is backwards.
type is 1 to include OBJ files in the search and the default, 0 will just include INT, MAC, INC, BAS.
nsp is the namespace to list from. If omitted, the query returns the routines from the current namespace. nsp can be either an explicit or an implied namespace.

• query RoutinesSortByField(Spec As %String(MAXLEN=512), Dir As %Integer, Type As %Integer, OrderBy As %String, nsp As %String)

Selects Name As %String(MAXLEN=256) As FileName/Ext, Size As %Integer, Date As %TimeStamp

This query provides a list of all routines that match the Spec ordered by the OrderBy. The Dir specifies the direction to search in, 1 is in assending order and -1 is in decending order.
Spec may contain both * and ? as wildcards. It may also consist of more than one, comma-delimited selections. For example:
"*.MAC"
"A*.MAC"
"A?.MAC"
"A*.MAC,B*.MAC"
The Type is 1 to include OBJ files in the search and the default, 0 will just include INT, MAC, INC, BAS.
OrderBy is one of:

Date - Date/Time the file was saved (the default)

Size - Size of the file

Type - Type of the file ie. INT, MAC, INC, BAS
If you wish to return the results in name order then use the RoutineList query as this is faster as it does not need to build a full list first in order to sort it correctly.
nsp is the namespace to list from. If omitted, the query returns the routines from the current namespace. nsp can be either an explicit or an implied namespace.


[BASEXML] > [%Library] > [Routine]		Private Storage