Usage Notes

The connection configuration string is implementation-specific. Different implementations of the Host Access Class Library may require different formats or information in the configuration string. This call is asynchronous in nature; the new connection may not yet be started when this call returns. An application can use the RegisterStartEvent function to be notified when a connection starts.

For Z and I Emulator for Windows, the configuration string has the following format:

PROFILE=[\"]<filename>[\"] [CONNNAME=<c>] [WINSTATE=<MAX|MIN|RESTORE|HIDE>]

Optional parameters are enclosed in square brackets []. The parameters are separated by at least one blank. Parameters may be in upper, lower, or mixed case and may appear in any order. The meaning of each parameter is as follows:

PROFILE=<filename>: Names the Z and I Emulator for Windows workstation profile (.WS file) that contains the connection configuration information. This parameter is not optional; a profile name must be supplied. If the file name contains blanks, the name must be enclosed in double quotation marks. The <filename> value may be either the profile name with no extension, the profile name with the .WS extension, or the fully-qualified profile name path.
CONNNAME=<c>: Specifies the connection name (EHLLAPI short session ID) of the new connection. This value must be a single, alphabetic character (A-Z or a-z). If this value is not specified, the next available connection name is assigned automatically. If a connection already exists with the specified name an error is thrown (ERRMAJ_INVALID_SESSION).
WINSTATE=<MAX|MIN|RESTORE|HIDE>: Specifies the initial state of the emulator window. The default if this parameter is not specified is RESTORE.

Note: Due to the asynchronous nature of this call, it is possible for this function to return without error, but the connection fails to start. For example, if two connections are started in a short period of time with the same connection name the second StartConnection does not fail because the first connection has not yet started. However, when the second connection finally attempts to register its name it does fail to start because the name is already in use by the first connection. To minimize this possibility, connections should be started without specifying the CONNNAME parameter if possible.