%Library.Routine

Class %Library.Routine Extends (%CharacterStream, %AbstractStream) [ Inheritance = right, System = 2 ]

The %Routine class provides a way to create and manipulate routines stored within a 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 ObjectScript 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()

Properties

RoutineName

Property RoutineName As %String;

The name of the routine.

RoutineType

Property RoutineType As %String;

The type of the routine.

RoutineVersion

Property RoutineVersion As %Integer;

Generated

Property Generated As %Boolean [ InitialExpression = 0 ];

True if this routine is generated from something else

UpToDate

Property UpToDate As %Boolean [ Calculated ];

For INT routines if this is compiled from a MAC then return true if the INT is up to date with the MAC, but if the INT is different to the MAC, e.g. it was modified and saved directly or the MAC was modified and saved but not compiled then it will return false.

For MAC routines it will be true if the generated pcode from compiling this MAC is up to date and false if recompiling this MAC would generate different pcode, so either the MAC has changed or the pcode has changed.

StoreGlvn

Property StoreGlvn As %String [ Calculated, Private ];

TempNode

Property TempNode As %String [ Private ];

NodeNo

Property NodeNo As %String [ InitialExpression = 0, Private ];

The current node we are reading from.

Buffer

Property Buffer As %Binary [ MultiDimensional, Private ];

Position

Property Position As %Integer [ InitialExpression = 2, Private ];

IOSize

Property IOSize As %Integer [ InitialExpression = 0, Private ];

IOLines

Property IOLines As %Integer [ InitialExpression = 0, Private ];

IOLangMode

Property IOLangMode As %Integer [ InitialExpression = 0, Private ];

IsModified

Property IsModified As %Boolean [ InitialExpression = 0 ];

TimeStamp

Property TimeStamp As %TimeStamp;

Locked

Property Locked As %Integer [ InitialExpression = 0 ];

Number of times this routine has been locked.

Name

Property Name As %String [ Calculated ];

The name (without extension) of the routine associated with this object.

This is for backwards compatibility only.

Namespace

Property Namespace As %String [ Calculated ];

Return the namespace this routine is from

LanguageMode

Property LanguageMode As %Integer [ Calculated ];

The language mode of this routine

Methods

UpToDateGet

Method UpToDateGet() As %Boolean

Lock

Method Lock() As %Status

Lock the current routine

Unlock

Method Unlock() As %Status

Unlock the current routine

LockRoutine

ClassMethod LockRoutine(name As %String, lock As %Boolean = 1, nsp As %String = {$namespace}, IModeLock As %Boolean = 0, timeout As %Integer = 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.

ParseRoutineName

Method ParseRoutineName(name As %String) As %Status [ Private ]

Split a routine name into its components; set the name,type etc.

If name has no extension, then the default is .MAC.

CheckProtect

ClassMethod CheckProtect(name As %String) As %Boolean

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

BuildRoutineName

Method BuildRoutineName() As %String [ CodeMode = expression, Private ]

Return the complete routine name for this routine.

%OnNew

Method %OnNew(initval As %String = "") As %Status [ Private ]

IOInit

Method IOInit() [ Private ]

Rewind

Method Rewind() As %Status

Flush

Method Flush() As %Status

SizeGet

Method SizeGet() As %Integer [ CodeMode = expression ]

Return the current size of the data stream.

IOGetStreamId

Method IOGetStreamId() As %String [ CodeMode = expression, Private ]

OpenStream

Method OpenStream(sid As %String) As %Status

SaveStream

Method SaveStream(supressbackup As %Boolean = 0, Output Refresh As %Boolean) As %Status

DeleteStream

ClassMethod DeleteStream(sid As %ObjectIdentity) As %Status

RoutineNameSet

Method RoutineNameSet(newvalue As %String) As %Status

Read

Method Read(ByRef len As %Integer = 32000, ByRef sc As %Status) As %String

ReadLine

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

Write

Method Write(data As %RawString = "") As %Status

WriteLine

Method WriteLine(data As %String = "") As %Status

InitWriteData

Method InitWriteData() As %Status [ Private ]

ReadIntoBuffer

Method ReadIntoBuffer() As %Boolean [ Private ]

Reads the next node into Buffer.

Returns 0 if there is no more data.

StoreGlvnGet

Method StoreGlvnGet() As %String [ Private ]

MoveToEnd

Method MoveToEnd() As %Status

Clear

Method Clear() As %Status

%OnClose

Method %OnClose() As %Status [ Private ]

NameGet

Method NameGet() As %String [ CodeMode = expression ]

NamespaceGet

Method NamespaceGet() As %String [ CodeMode = expression ]

LanguageModeGet

Method LanguageModeGet() As %Integer [ CodeMode = expression ]

LanguageModeSet

Method LanguageModeSet(languagemode As %Integer) As %Status

Compile

Method Compile(qspec As %String) As %Status

Compile this routine.

For information on qSpec, see System Flags and Qualifiers.

GetCurrentTimeStamp

Method GetCurrentTimeStamp() As %TimeStamp

Get the on-disk timestamp for the routine.

Save

Method Save(supressbackup As %Boolean = 0) As %Status [ CodeMode = expression ]

Save this routine.

Delete

ClassMethod Delete(rtnname As %String, flag As %String = 0, supressbackup As %Boolean = 0, nsp As %String = {$namespace}) As %Status

Delete the routine rtnname. If the rtnname is not fully qualified we will resolve this into a fully qualified name first and then proceed with the rest of the delete. For example if you specify 'test' and there is a 'test.mac' it will resolve to this, if there was only a 'test.obj' it will resolve the name to this. The parameter flag specifies how 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.

RoutineExists

Method RoutineExists() As %Boolean [ CodeMode = expression ]

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

Exists

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

GetDate

ClassMethod GetDate(name As %String) As %TimeStamp

Return the timestamp the routine with name was last updated.

CheckSyntax

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)

RoutineListExecute

ClassMethod RoutineListExecute(ByRef QHandle As %Binary, ByRef spec As %String(MAXLEN=512) = "", Dir As %Integer = 1, Type As %Integer = 0, Nsp As %String = {$namespace}, nolang As %Boolean = 0) As %Status [ Final ]

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.

RoutineListClose

ClassMethod RoutineListClose(QHandle As %Binary) As %Status

RoutineListFetch

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.

RoutineListFetchRows

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.

RoutinesSortByFieldExecute

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 = {$namespace}) As %Status [ Final ]

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.

RoutinesSortByFieldClose

ClassMethod RoutinesSortByFieldClose(QHandle As %Binary) As %Status

RoutinesSortByFieldFetch

ClassMethod RoutinesSortByFieldFetch(ByRef QHandle As %Binary, ByRef Row As %List, ByRef AtEnd As %Integer = 0) As %Status [ CodeMode = expression ]

Fetch returns the next row in the query.

RoutinesSortByFieldFetchRows

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.

LastModifiedGet

Method LastModifiedGet() As %TimeStamp [ CodeMode = expression ]

FindClose

ClassMethod FindClose(ByRef qHandle As %Binary) As %Status [ Internal, PlaceAfter = FindExecute ]

FindExecute

ClassMethod FindExecute(ByRef qHandle As %Binary, Namespace As %String, RoutineName As %String, FindWhat As %String = "", MatchCase As %Boolean = 1) As %Status [ Internal ]

FindFetch

ClassMethod FindFetch(ByRef qHandle As %Binary, ByRef Row As %List, ByRef AtEnd As %Integer = 0) As %Status [ Internal, PlaceAfter = FindExecute ]

CompareClose

ClassMethod CompareClose(ByRef qHandle As %Binary) As %Status [ Internal, PlaceAfter = CompareExecute ]

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.

CompareExecute

ClassMethod CompareExecute(ByRef qHandle As %Binary, Nsp1 As %String, RouName1 As %String, Nsp2 As %String = "", RouName2 As %String) As %Status [ Internal ]

RoutineCompare

ClassMethod RoutineCompare(Nsp1 As %String = "", RouName1 As %String = "", Nsp2 As %String = "", RouName2 As %String = "", GloRef As %String) As %Status [ Internal ]

CompareFetch

ClassMethod CompareFetch(ByRef qHandle As %Binary, ByRef Row As %List, ByRef AtEnd As %Integer = 0) As %Status [ Internal, PlaceAfter = FindExecute ]

LineTerminatorGet

Method LineTerminatorGet() 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.

GetObjectVersion

Method GetObjectVersion() As %Numeric

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

normalizeName

ClassMethod normalizeName(ByRef rtn As %String, ByRef nm As %String, ByRef type As %String, obj As %Boolean = 1) As %Status [ Private ]

GetRoutineGlobals

ClassMethod GetRoutineGlobals(ByRef Names As %String) As %Status

Return list of globals where routine and class information is stored.
Returns Names="ROUTINE,rBACKUP,rINC,rINCSAVE,rINDEX,rMAC,rMACSAVE,rMAP,rOBJ,oddDEF"
Here is some documentation on the format of the routine globals.

ROUTINE - Native .INT COS code, generated from .MAC, or generated from classes. When compiled generates .OBJ code.
ROUTINE(Name,0)=timestamp when last saved
ROUTINE(Name,0,0)=# lines in routine
ROUTINE(Name,0,1...x) = Source Lines in routine
ROUTINE(Name,0,"GENERATED")= 0/1 whether routine is generated or native
ROUTINE(Name,0,"INC",IncludeFileName1)=Timestamp when last include file last saved
ROUTINE(Name,0,"INC",IncludeFileName2)=Timestamp when last include file last saved
ROUTINE(Name,0,"SIZE")=# bytes in routine
ROUTINE(Name,0,"LANG")=language mode

ROUTINE(Name,"MAC")=Timestamp of .MAC code when last saved if generated
rBACKUP(Name,Type,version) - backup of ^ROUTINE, created by the command Merge ^rBACKUP(rtn,type,nextverersion)=^ROUTINE(rtn) where type="INT/MVI/BAS"

rINC - Native .INT or macro code, compiled into .MAC when included with #include directive
rINC(Name,0)=timestamp when last saved
rINC(Name,0,0)=# lines in include file
rINC(Name,0,1...x) = Source Lines in include file
rINC(Name,0,"SIZE")=# bytes in include file
rINC("ZZ","P") - Meta data used for precompiling include files

rINCSAVE - Backup of ^rINC, created by the command Merge ^rINCSAVE(rtn,nextver)=^rINC(rtn,0)

rINDEX - Index of .OBJ, .INT, and .MAC routines
rINDEX(Name,"OBJ/MAC/INC")=$lb(Time compiled,Size)
rINDEX(Name,"INT")=$lb(Time compiled,Size,Generated 0/1)

rMAC - Native .MAC Macro code which when compiled generates .INT code
rMAC(Name,0)=Timestamp when last saved
rMAC(Name,0,0)=#lines in routine
rMAC(Name,0,1...x) = Source Lines in routine
rMAC(Name,0,"SIZE")=# bytes in routine

rMACSAVE(Name,Type,version) - backup of ^rMAC, created by the command Merge ^rMACSAVE(rtn,nextver)=^rMAC(rtn,0)

rMAP - Debug map used by the debugger and for error trapping
rMAP(Name,"INT","MAC",offsets)=$lb(debuginfo)
rMAP(Name,"MAC","INT",offsets)=$lb(debuginfo)

rOBJ - Compiled .INT code
rOBJ(Name,"INT")=timestamp of .INT code when compiled
rOBJ(Name,0...n)=Compiled object code

oddDEF - Source code for classes
oddDEF($zcvt(Name,"U"),....)=source code from class. Note that all of the other odd* nodes are meta data describing the class, and can be recreated by compiling the class. The rINDEXCLASS and rINDEXSQL nodes also get recreated when compiling the class.

CompileList

ClassMethod CompileList(rtns As %String, qspec As %String) As %Status

Compile a list of routines in the current namespace. Pass this a comma separated list of items, which can include wild card characters e.g. 'test.mac,abc*.int' or pass in a subscripted array with the routine name as the subscript. It will return an error %Status. If you do not wish to use multicompile then pass in /multicompile=0

CompileAll

ClassMethod CompileAll(Flags As %String = 0, IO As %String = {$p}, ByRef Count As %Integer, ByRef Errors As %Integer, MultiCompile As %Integer, Journal As %Integer, KeepSource As %Boolean = 1) 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.
MultiCompile - If true then use multiple jobs to do the compile, if not specified use the default /multicompile qualifier setting
Journal - If true then journal the compile, if false disable journaling for compile, if not specified use the default /journal qualifier setting
KeepSource - If true (default) then keep INT code from compiling a MAC, if false then do not save INT code

CompileSelected

ClassMethod CompileSelected(Mask As %String = "*.*", Flags As %String = 0, IO As %String = {$p}, ByRef Count As %Integer, ByRef Errors As %Integer, MultiCompile As %Integer, Journal As %Integer, KeepSource As %Boolean = 1) As %Status

Compile selected routines in a namespace.
Mask Selection mask of which routines to compile. This mask is passed to %Library.Routine.RoutineList() and must be in a format it understands.
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.
MultiCompile - If true then use multiple jobs to do the compile, if not specified use the default /multicompile qualifier setting
Journal - If true then journal the compile, if false disable journaling for compile, if not specified use the default /journal qualifier setting
KeepSource - If true (default) then keep INT code from compiling a MAC, if false then do not save INT code

CompileAllNamespaces

ClassMethod CompileAllNamespaces(Flags As %String = 0, IO As %String = {$p}, ByRef Count As %Integer, ByRef Errors As %Integer, MultiCompile As %Integer = 1, Journal As %Integer = 1, KeepSource As %Boolean = 1) 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.
MultiCompile - If true (default) then use multiple jobs to do the compile
Journal - If true (default) then journal the compile, if false disable journaling for compile
KeepSource - If true (default) then keep INT code from compiling a MAC, if false then do not save INT code

%ExistsId

ClassMethod %ExistsId(id As %String) As %Boolean [ CodeMode = expression ]

%IsModified

Method %IsModified() As %Integer

%ObjectModified

Method %ObjectModified() As %Integer