This video is part of the [Tutorial Series] Getting Started with ZOS-API free tutorial.
The DDE capability was removed from Ansys Zemax OpticStudio in version 2022 R2 due to it being deprecated by Microsoft. The DDE was replaced by a .NET-based language: the ZOS-API. .NET is a modern language that makes it relatively easy to pass arbitrary data between applications, and is designed to be used in an object-oriented environment. This article is provided for users to convert their DDE script into the more modern ZOS-API programming language. This article contains a table mapping the old DDE data items to the new ZOS-API methods.
Authored By Thomas Pickering
Extensions Help
The table in the next section maps the old DDE data items to the new ZOS-API methods. You can find a list of all DDE data items and their syntax in the Extensions Help.
List of DDE data items and equivalent method in ZOS-API
| DDE data item | ZOS-API method | ZOS-API path |
|---|---|---|
| CloseUDOData | User-defined operands wait until the plugin application shuts down. | |
| DeleteConfig | IMultiConfigEditor.DeleteConfiguration | TheSystem.MCE |
| DeleteMCO | IMultiConfigEditor.RemoveOperandAt | TheSystem.MCE |
| DeleteMFO | IMeritFunctionEditor.RemoveOperandAt | TheSystem.MFE |
| DeleteObject | INonSeqEditor.RemoveObjectAt | TheSystem.NCE |
| DeleteSurface | ILensDataEditor.RemoveSurfaceAt | TheSystem.LDE |
| ExportCAD | IExportCAD.* | TheSystem.Tools.OpenExportCAD() |
| ExportCheck | No equivalent needed. See IExportCAD. | |
| FindLabel | ILensDataEditor.FindLabel() | TheSystem.LDE |
| GetAddress | Not yet implemented. | |
| GetAperture | ILDEApertureData.CurrentTypeSettings | TheSystem.LDE.GetSurfaceAt().ApertureData |
| Parameters are specific to aperture type. Type-specific settings can be found on SNone, SSpider, SUserAperture, etc. | ||
| GetApodization | ILensDataEditor.GetApodization() | TheSystem.LDE |
| GetAspect | Not yet implemented. | |
| GetBuffer | IUserAnalysisData.UserSettings | TheApplication.UserAnalysisData |
| GetComment | ILDERow.Comment | TheSystem.LDE.GetSurfaceAt() |
| Also available by retrieving the appropriate row cell | ||
| GetConfig | IMultiConfigEditor.CurrentConfiguration IMultiConfigEditor.NumberOfConfigurations IMultiConfigEditor.NumberOfOperands |
TheSystem.MCE |
| GetDate | IZOSAPI_Application.GetDate() | TheApplication |
| GetExtra | ILDERow.GetSurfaceCell() | TheSystem.LDE |
| GetField | IField.* | TheSystem.SystemData.Fields.GetField() |
| GetFile | IOpticalSystem.SystemFile | TheSystem |
| GetFirst | ILensDataEditor.GetFirstOrderData() | TheSystem.LDE |
| GetGlass | ILensDataEditor.GetGlass() | TheSystem.LDE |
| GetGlobalMatrix | ILensDataEditor.GetGlobalMatrix() | TheSystem.LDE |
| GetIndex | ILensDataEditor.GetIndex() | TheSystem.LDE |
| GetLabel | ILensDataEditor.GetLabel() | TheSystem.LDE |
| GetMetaFile | Not supported. | |
| GetMulticon | IMCERow.* | TheSystem.MCE.GetOperandAt() |
| GetName | IOpticalSystem.SystemName | TheSystem |
| GetNSCData | INonSeqEditor.NumberOfObjects | TheSystem.NCE |
| GetNSCMatrix | INonSeqEditor.GetMatrix() | TheSystem.NCE |
| GetNSCObjectData | INCERow.* | TheSystem.NCE.GetObjectAt() |
| GetNSCObjectFaceData | INCECoatScatterFaceData.* | TheSystem.NCE.GetObjectAt().CoatScatterData |
| IObjectScatteringSettings.* | ||
| Parameters are specific to model. Type-specific settings can be found on S_None, S_Lambertian, etc. | ||
| GetNSCParameter | INCERow.GetObjectCell() | TheSystem.NCE.GetObjectAt() |
| GetNSCPosition | INCERow.XPosition/YPosition/etc. | TheSystem.NCE.GetObjectAt() |
| GetNSCProperty | INCERow.* | TheSystem.NCE.GetObjectAt() |
| Parameters found on various sub interfaces | ||
| GetNSCSettings | ISDNonSeqData | TheSystem.SystemData.NonSequentialData |
| GetNSCSolve | IEditorCell.Solve | TheSystem.NCE.GetObjectAt().GetObjectCell() |
| GetOperand | IMeritFunctionEditor.GetOperandAt() | TheSystem.MFE |
| GetPath | IZOSAPI_Application.SamplesDir IOpticalSystem.SystemFile |
TheApplication TheSystem |
| GetPolState | ISDPolarizationData.* | TheSystem.SystemData.Polarization |
| GetPolTrace | IRayTraceNormPolData.* | TheSystem.Tools.OpenBatchRayTrace.CreateNormPol() |
| GetPolTraceDirect | IRayTraceDirectPolData.* | TheSystem.Tools.OpenBatchRayTrace.CreateDirectPol() |
| GetPupil | ILensDataEditor.GetPupil() | TheSystem.LDE |
| GetRefresh | Not applicable. | |
| GetSag | ILensDataEditor.GetSag() | TheSystem.LDE |
| GetSequence | Not applicable. | |
| GetSerial | IZOSAPI_Application.SerialCode | TheApplication |
| GetSettingsData | ISettingsData.* | TheApplication.UserAnalysisData.UserSettings |
| GetSolve | IEditorCell.Solve | TheSystem.LDE.GetSurfaceAt().GetSurfaceCell() |
| GetSurfaceData | ILDERow.* | TheSystem.LDE.GetSurfaceAt() |
| Some parameters found on various sub interfaces. | ||
| GetSurfaceDLL | ISurfaceTypeSettings.FileName | TheSystem.LDE.GetSurfaceAt().CurrentTypeSetings |
| GetSurfaceParameter | ILDERow.GetSurfaceCell() | TheSystem.LDE.GetSurfaceAt() |
| GetSystem | ISystemData.* | TheSystem.SystemData |
| GetSystemAper | ISDApertureData.* | TheSystem.SystemData |
| GetSystemProperty | ISystemData.* | TheSystem.SystemData |
| GetTextFile | IAR_.GetTextFile | TheSystem.Analyses.New_AnalysisForIndex().GetResults() |
| GetTol | ITDERow.* | TheSystem.TDE.GetOperandAt() |
| GetTrace | IRayTraceNormUnpolData.* | TheSystem.Tools.OpenBatchRayTrace.CreateNormUnpol() |
| GetTraceDirect | IRayTraceDirectUnpolData.* | TheSystem.Tools.OpenBatchRayTrace.CreateDirectUnpol() |
| GetUDOSystem | Not applicable. | |
| GetUpdate | IOpticalSystem.UpdateStatus() | TheSystem |
| GetVersion | IZOSAPI_Application.OpticStudioVersion | TheApplication |
| GetWave | IWavelength.* | TheSystem.SystemData.Wavelenghts.GetWavelength() |
| GlobalToLocal | ILensDataEditor.RunTool_ConvertGlobalToLocalCoordinates() | TheSystem.LDE |
| Hammer | IHammerOptimization.* | TheSystem.Tools.OpenHammerOptimization() |
| ImportExtraData | ILDEImportData.ImportDataFile | TheSystem.LDE.GetSurfaceAt().ImportData |
| InsertConfig | IMultiConfigEditor.InsertConfiguration() | TheSystem.MCE |
| InsertMCO | IMultiConfigEditor.InsertNewOperandAt() | TheSystem.MCE |
| InsertMFO | IMeritFunctionEditor.InsertNewOperandAt() | TheSystem.MFE |
| InsertObject | INonSeqEditor.InsertNewObjectAt() | TheSystem.NCE |
| InsertSurface | ILensDataEditor.InsertNewSurfaceAt() | TheSystem.LDE |
| LoadDetector | INonSeqEditor.LoadDetector() | TheSystem.NCE |
| LoadFile | IOpticalSystem.LoadFile() | TheSystem |
| IZOSAPI_Application.LoadNewProject() | TheApplication | |
| LoadMerit | IMeritFunctionEditor.LoadMeritFunction() | TheSystem.MFE |
| LoadTolerance | IToleranceDataEditor.LoadToleranceFile() | TheSystem.TDE |
| LocalToGlobal | ILensDataEditor.RunTool_ConvertLocalToGlobaCoordinates() | TheSystem.LDE |
| MakeGraphicWindow | IUserAnalysisData.* | TheApplication.UserAnalysisData |
| Not compatible with DDE format. | ||
| MakeTextWindow | IUserAnalysisData.* | TheApplication.UserAnalysisData |
| ModifySettings | IAS_.ModifySettings() | TheSystem.Analyses.New_AnalysisForIndex().GetSettings() |
| NewLens | IOpticalSystem.New() | TheSystem |
| NSCCoherentData | INonSeqEditor.GetCoherentData() | TheSystem.NCE |
| NSCDetectorData | INonSeqEditor.GetDetectorData() | TheSystem.NCE |
| NSCLightningTrace | ILightningTrace.* | TheSystem.Tools.OpenLightningTrace() |
| NSCTrace | INSCRayTrace.* | TheSystem.Tools.OpenNSCRayTrace() |
| OpenWindow | I_Analyses.* | TheSystem.Analyses |
| OperandValue | IMeritFunctionEditor.GetOperandValue() | TheSystem.MFE |
| Optimize | ILocalOptimization.* | TheSystem.Tools.OpenLocalOptimization() |
| PushLens | Not applicable. | |
| PushLensPermission | Not applicable. | |
| QuickFocus | IQuickFocus.* | TheSystem.Tools.OpenQuickFocus() |
| ReleaseWindow | User defined analyses wait until the plugin application shuts down. | |
| RemoveVariables | IOpticalSystemTools.RemoveAllVariables() | TheSystem.Tools |
| SaveDetector | INonSeqEditor.SaveDetector() | TheSystem.NCE |
| SaveFile | IOpticalSystem.SaveAs() | TheSystem |
| SaveMerit | IMeritFunctionEditor.SaveMeritFunction | TheSystem.MFE |
| SaveTolerance | IToleranceDataEditor.SaveToleranceFile() | TheSystem.TDE |
| SetAperture | ISurfaceApertureType.* | TheSystem.LDE.GetSurfaceAt().ApertureData.CurrentTypeSettings |
| SetBuffer | IUserAnalysisData.UserSettings | TheApplication.UserAnalysisData |
| SetConfig | IMultiConfigEditor.SetCurrentConfiguration() | TheSystem.MCE |
| SetExtra | ILDERow.GetSurfaceCell() | TheSystem.LDE |
| SetField | IField.* | TheSystem.SystemData.Fields.GetField() |
| SetFloat | IOpticalSystem.SystemFile | TheSystem |
| SetLabel | ILensDataEditor.SetLabel() | TheSystem.LDE |
| SetMulticon | IMCERow.* | TheSystem.MCE.GetOperandAt() |
| SetNSCObjectData | INCERow.* | TheSystem.NCE.GetObjectAt() |
| SetNSCObjectFaceData | INCECoatScatterFaceData.* IObjectScatteringSettings.* |
TheSystem.NCE.GetObjectAt().CoatScatterData |
| Parameters are specific to model. Type-specific settings can be found on S_None, S_Lambertian, etc. | ||
| SetNSCParameter | INCERow.XPosition/YPosition/etc. | TheSystem.NCE.GetObjectAt() |
| SetNSCPosition | INCERow.GetObjectCell() | TheSystem.NCE.GetObjectAt() |
| SetNSCProperty | INCERow.* | TheSystem.NCE.GetObjectAt() |
| Parameters found on various sub interfaces. | ||
| SetNSCSettings | ISDNonSeqData | TheSystem.SystemData.NonSequentialData |
| SetNSCSolve | IEditorCell.Solve | TheSystem.NCE.GetObjectAt().GetObjectCell() |
| SetOperand | IMeritFunctionEditor.GetOperandAt() | TheSystem.MFE |
| SetPolState | ISDPolarizationData.* | TheSystem.SystemData.Polarization |
| SetSettingsData | ISettingsData.* | TheApplication.UserAnalysisData.UserSettings |
| SetSolve | IEditorCell.Solve | TheSystem.LDE.GetSurfaceAt().GetSurfaceCell() |
| SetSurfaceData | ILDERow.* | TheSystem.LDE.GetSurfaceAt() |
| Some parameters found on various sub interfaces. | ||
| SetSurfaceParameter | ILDERow.GetSurfaceCell() | TheSystem.LDE.GetSurfaceAt() |
| SetSystem | ISystemData.* | TheSystem.SystemData |
| SetSystemAper | ISDApertureData.* | TheSystem.SystemData |
| SetSystemProperty | ISystemData.* | TheSystem.SystemData |
| SetTol | ITDERow.* | TheSystem.TDE.GetOperandAt() |
| SetUDOData | IZOSAPI_Application.OperandResults.* | TheApplication |
| SetUDOItem | IVectorData.* | TheApplication.OperandResults |
| SetVig | Ifields.SetVignetting() | TheSystem.SystemData.Fields |
| SetWave | IWavelength.* | TheSystem.SystemData.Wavelenghts.GetWavelength() |
| WindowMaximize | Not yet implemented. | |
| WindowMinimize | Not yet implemented. | |
| WindowRestore | Not yet implemented. | |
Notes
- TheApplication = Instance of IZOSAPI_Application, as referred to in the Interface documentation.
Note that there should only be one instance for a single application.
- TheSystem = Instance of IOpticalSystem, as referred to in the Interface documentation.
Note that there could be multiple instances for a single application.
FAQ
How to “PushLens” with ZOS-API?
For DDE Extensions, “PushLens” will take the lens currently loaded in the server's memory and push it into the Lens Data Editor. In ZOS-API this can be done:
- In the Interactive Extension mode. The LDE is automatically updated.
- In ZOS-API Extensions compiled as executables.
The user can either choose to automatically update the OpticStudio UI as changes are made, or to suppress changes. This setting can be changed at any time from within the extensions. By default, ZOS-API Extensions execute on the currently open lens file, but the user can choose to work on a temporary system instead, which will not affect the primary system.
Please see the help file section entitled “Plug-In/Extension” (The Programming Tab > About the ZOS-API > Plug-In/Extension).
How to “GetRefresh” with ZOS-API?
For DDE Extensions, “GetRefresh” will cause OpticStudio to copy all lens data (wavelengths, fields, editors, etc.) into the stored copy of the server. The lens is then updated, which means OpticStudio recomputes all pupil positions, solves, and index data.
In ZOS-API, retrieving the lens data from ZOS to the application is done manually by reaching into class properties (i.e. the ILDERow class) and retrieving the lens data.
This article is part of the [Tutorial Series] Getting Started with ZOS-API free tutorial.
Previous Article: The differences between ZOS-API, ZPL and DLL
Next Article: Required OpticStudio version and language for using ZOS-API