%SYNC.Transporter

class %SYNC.Transporter extends %Library.RegisteredObject

%SYNC.Transporter is a utility class used to transport objects from one Cache namespace to another.

SYNC Transporter

SYNC Transporter

Overview

%SYNC.Transporter is a utility class used to export and import objects from one Cache namespace to another. Raw object data is copied to a transport container global. The transport container global is then exported to a file and moved to the desired location where it can be imported into another Cache namespace. The import namespace must contain runnable classes corresponding to type of each object contained in the transport container. IDs and references can be abstracted during transport and resolved on import to the correct ID value as it exists in the import namespace.

Create a Transport Container

To transport objects using the Transporter, simply instantiate the Transporter and add the desired objects. When all objects are in the transport container, export it to a file. The following method that transports instances of Sample.Person to a transport container is implemented as:

  classmethod TransportByState(pState as %String(MAXLEN=2) = "MA", pDirectory as %String = "") as %Status {
  	try {
  		set statement = ##class(%SQL.Statement).%New()
  		set statement.%ObjectSelectMode = 1
  		do statement.prepare("select %ID as ID from Sample.Person where home_state = ?")
  		set persons = statement.%Execute(pState)
  		set transporter = ##class(%SYNC.Transporter).%New()
  		while persons.%Next() { set tSC = transporter.AddObject(persons.ID.%Oid()) write !,$Select($$$ISOK(tSC):"Successfully added ",1:"Error occurred adding "),persons.ID.%Id()," ",persons.ID.Name," to the transporter" }
  		do transporter.ExportFile(pDirectory _ "people"_pState_".gof")
  		set tSC = $$$OK
  	}
  	catch tException {
  		set tSC = tException.AsStatus()
  	}
  	quit tSC
  }

Running this method produces the following output:

		SAMPLES>d ##class(Sample.Person).TransportByState("NY","/Users/test/Downloads/")
		
		Successfully added 12 Nathanson,Debra I. to the transporter
		Successfully added 19 North,Molly K. to the transporter
		Successfully added 71 Grabscheid,Lawrence A. to the transporter
		Successfully added 108 Massias,Mary I. to the transporter
		Successfully added 179 Eastman,Lawrence M. to the transporter
		Successfully added 188 Ihringer,Dmitry G. to the transporter
		Successfully added 195 Isaacs,Dmitry A. to the transporter
		Exporting to GO/GOF format started on 12/12/2011 08:31:33
		Exporting global: ^OBJ.EXP.37
		Export finished successfully.

The file, peopleNY, created by running the example above now contains the object data for each of the objects selected by the dynamic SQL statement. The file also contains abstracted keys for each of the objects referenced by the objects explicitly added to the transport container. It is the user's responsiblity to explicitly add referenced objects if more than the key is required. For example, if the Company object referenced by an Employee object needs to transported then it must be added explicitly by calling AddObject and passing it the OID of the Company object.

The transport file can be moved to a place where it is visible to the Cache namespace where it is to be imported. To import a transport file, simply instantiate the %SYNC.Transporter class and call the Import method. The following example simply imports the transport file back into the same namespace where it was produced. The rows transported are deleted first to demonstrate the Import behavior.

		SAMPLES>d $system.SQL.Shell()
		SQL Command Line Shell
		----------------------------------------------------
		
		The command prefix is currently set to: <>.
		Enter q to quit, ? for help.
		SAMPLES>>delete from Sample.Person where home_state = ?
		2.	delete from Sample.Person where home_state = ?
		
		
		Enter the value for parameter '1': NY
		executing statement with parameter values: set %tResult=%tStatement.%Execute("NY")
		7 Rows Affected
		statement prepare time: 0.0157s, elapsed execute time: 0.0337s.
		---------------------------------------------------------------------------
		SAMPLES>>q
		SAMPLES>set status = transporter.Import("/Users/danp/Downloads/peopleNY.gof",.count,.errors)
		
		SAMPLES>write status
		1
		SAMPLES>write count
		7
		SAMPLES>zw errors
		errors=0
		
		SAMPLES>d $system.SQL.Shell()
		SQL Command Line Shell
		----------------------------------------------------
		
		The command prefix is currently set to: <>.
		Enter q to quit, ? for help.
		SAMPLES>>select %id,name from sample.person where home_state = ?
		1.	select %id,name from sample.person where home_state = ?
		
		Enter the value for parameter '1': NY
		executing statement with parameter values: set %tResult=%tStatement.%Execute("NY")
		ID	Name	
		12	Nathanson,Debra I.
		19	North,Molly K.
		71	Grabscheid,Lawrence A.
		108	Massias,Mary I.
		179	Eastman,Lawrence M.
		188	Ihringer,Dmitry G.
		195	Isaacs,Dmitry A.
		
		7 Rows(s) Affected
		statement prepare time: 0.0847s, elapsed execute time: 0.0012s.
		---------------------------------------------------------------------------
		SAMPLES>>

After creating a transport container it is a good idea to delete the global used by calling DeleteTransportGlobal().

Property Inventory

transportGlobal

Properties

property transportGlobal as %String (MAXLEN = 250);

transportGlobal is the name of the global that will contain transported objects.

Property methods: transportGlobalDisplayToLogical(), transportGlobalGet(), transportGlobalIsValid(), transportGlobalLogicalToDisplay(), transportGlobalLogicalToOdbc(), transportGlobalNormalize(), transportGlobalSet()

Methods

method AddObject(pOID As %ObjectIdentity = "", pDepth As %Integer = 1) as %Status

AddObject adds the object whose OID is pOID to the transport container if that object is not already present in the container. Objects can be present in the container as either a complete object or as a simple OID reference.

If pDepth is 0 (zero) and the object is not already present in the container then the complete object is added.

If pDepth is 1 (one) and the complete object is not already present in the container then the complete object and the key of each object referenced by that object are added.

classmethod DeleteTransportGlobal(pTransportId As %CacheString = "") as %Status

This method should be used to delete the transport global when it is no longer needed. The pTransportId is the integer appended to "^OBJ.EXP." to form the transport global name.

method ExportFile(pFile As %String = "", qspec As %String = "") as %Status

ExportFile will export the current transport container to the pFile file.

method Import(pFile As %String = "", ByRef pCount=0, ByRef errorlog As %String = 0) as %Status

Import is the method to call to import a transport container from a file. Each object contained in the transport container is loaded into the current namespace. The number of objects found in the container and a log of all errors encountered during import is returned to the caller.