> For the complete documentation index, see [llms.txt](https://www.opal-rt.com/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://www.opal-rt.com/docs/rt-lab/automation-api-and-scripting/rt-lab-api/c-rt-lab-api-reference/functions-reference/opalconnectbyname-deprecated.md).

# OpalConnectByName (deprecated)

<table data-header-hidden><thead><tr><th width="199.77783203125"></th><th></th></tr></thead><tbody><tr><td><strong>Group</strong></td><td>Model Selection</td></tr><tr><td><strong>Description</strong></td><td><p>Connects the API to an active model. Subsequent API calls refer to this model.<br>When trying to establish a connection with a model when there are multiple models that correspond to the specified <strong>ModelName</strong> and <strong>ModelPath</strong>, a window is displayed prompting you to choose a model. This may occur when:</p><ul><li><strong>modelName</strong> is not NULL. The window displays a list of active models with the specified <strong>ModelName</strong> and <strong>ModelPath</strong>, unless <strong>ReturnOnAmbiguity</strong> is set to <strong>True1</strong>.</li></ul><p><img src="https://96827845-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FNRdpSk8kjn20gXAexnt6%2Fuploads%2Fgit-blob-49aa85359722d2dee0b0c18009f480706a541661%2FCapi-opalconnectbyname.png?alt=media" alt="" data-size="original"></p><ul><li><strong>modelName</strong> is not NULL, there is more than one active model with a specified path and name and <strong>returnOnAmbiguity</strong> is <strong>False(0)</strong>.</li></ul><p><br><strong>exactMatch exactMatch modelName returnOnAmbiguity E2BIG</strong></p></td></tr><tr><td><strong>Required Control</strong></td><td>None</td></tr><tr><td><strong>Usage</strong></td><td>int <strong>OpalConnectByName</strong> (const char *modelName,const char *modelPath, unsigned short exactMatch, unsigned short systemControl,unsigned short returnOnAmbiguity, OP_API_INSTANCE_ID *pInstId, OP_MODEL_STATE*pModelState);</td></tr><tr><td><strong>Input</strong></td><td><ul><li><strong>modelName:</strong> name of the model to which connection is desired</li><li><strong>modelPath:</strong> Path where original model resides. May be NULL; used to resolve ambiguity when more than one model of the same name are active.</li><li><strong>exactMatch:</strong> True(1) to request an exact name match.</li><li><strong>systemControl:</strong> True(1) to request control of the model.</li><li><strong>returnOnAmbiguity:</strong> No window is displayed, an error code (E2BIG) isreturned.</li></ul></td></tr><tr><td><strong>Output</strong></td><td><ul><li><strong>instId:</strong> Current active model’s instance ID. See <strong>Glossary</strong>.</li><li><strong>modelState:</strong> Current model's state.</li></ul></td></tr><tr><td><strong>Return value</strong></td><td><ul><li><strong>EOK:</strong> Success.</li><li><strong>EIO:</strong> Error sending the request or receiving the reply.</li><li><strong>ENOENT:</strong> No active model found.</li><li><strong>OP_API_CMD_CANCELED:</strong> Active model(s) found but no model has been selected.</li><li><strong>ENOSPC:</strong> No active model with specified name, path and type.</li><li><strong>E2BIG:</strong> More than 1 active models with specified name and path (only if returnOnAmbiguity is TRUE).</li><li><strong>EPERM:</strong> Control requested, but already given to another client.</li><li><strong>ENOEXEC:</strong> Could not connect to model. Not all of the subsystems are still active.</li><li><strong>ENOMEM:</strong> Internal memory allocation error.</li><li><strong>OP_API_EBAD_CONFIG:</strong> Node mapping not valid or IP address of controllermachine not specified (environment variable OPAL_META_CTL_IP not set).</li><li><strong>OP_API_EBAD_PHYS_NODE:</strong> Physical node not found.</li><li><strong>OP_API_ECREATE_SHMEM:</strong> Could not create shared memory.</li><li><strong>OP_API_ECREATE_PROCESS:</strong> Error launching OpalChooseModel.exe - Error displayingthe dialog box. Process OpalChooseModel.exe is called by this function. This process is placed RTLAB_ROOT\common\bin folder.</li><li><strong>OP_API_ENO_LICENSE:</strong> No license for one or more of RT-LAB components.</li><li><strong>OP_API_ENO_PRODUCT:</strong> No license for RT-LAB and RT-LABx.</li><li><strong>OP_API_MODEL_IO_</strong> <strong>TIMEOUT</strong></li><li><strong>OP_API_MODEL_IO_ERROR:</strong> Model is missing some or all processes or subsystems.</li></ul></td></tr><tr><td><strong>Examples</strong></td><td>See the example <strong>basic_example1</strong>.</td></tr><tr><td><strong>Related items</strong></td><td>OpalSetCurrentModel, OpalGetActiveProjects, OpalConnect (deprecated), OpalDisconnect (deprecated), OpalOpenProject, OpalCloseProject, OpalGetModelState</td></tr></tbody></table>


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://www.opal-rt.com/docs/rt-lab/automation-api-and-scripting/rt-lab-api/c-rt-lab-api-reference/functions-reference/opalconnectbyname-deprecated.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
