Skip to main content

%SYNC.Transporter

Class %SYNC.Transporter Extends %RegisteredObject [ System = 3 ]

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

SYNC Transporter

Overview​

%SYNC.Transporter is a utility class used to export and import objects from one 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 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 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.

Properties​

transportGlobal​

Property transportGlobal As %String(MAXLEN = 250);

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

transporter​

Property transporter As %String(MAXLEN = "") [ Internal, MultiDimensional ];

objectStack​

Property objectStack As %Integer [ Internal ];

Methods​

%OnNew​

Method %OnNew(initvalue As %RawString = "") As %Status [ Private, ProcedureBlock = 1 ]

This callback method is invoked by the %New method to provide notification that a new instance of an object is being created.

If this method returns an error then the object will not be created. This method initializes a new transporter global unless the user passes the transporterId when instantiating this class. In that case, it is assumed that the user wishes to add to an existing transporter global and the global is not initialized if it exists.

DeleteTransportGlobal​

ClassMethod DeleteTransportGlobal(pTransportId As %RawString = "") As %Status [ ProcedureBlock = 1 ]

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.

GlobalName​

Method GlobalName() As %String [ CodeMode = expression, Internal ]

Import​

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.

loadTransportContainer​

Method loadTransportContainer(pFile As %String = "") As %Status [ Internal ]

loadTransportContainer is an internal method called by Import to import the transport container from pFile. This method returns a %Library.Status value indicating success or failure.

ExportFile​

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

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

AddObject​

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.

getTransporter​

Method getTransporter(pClass, ByRef pSC As %Library.Status) As %String [ Internal ]

Internal method to return the name of the routine that implements the transporter for pClass. If the transporter is not yet generated for pClass then the generator is called. If no transporter is found and the generator fails then NULL is returned.