Opening the Port

The first step in using the API is to gain access to a port with the MgslOpen call. The application specifies an integer port identifier. If the specified port does not exist, then ERROR_BAD_DEVICE is returned. If the port exists but is in use by another application, then ERROR_DEVICE_IN_USE is returned. If the port exists and is not in use, then ERROR_SUCCESS and a device handle for the port is returned. Most API calls use the device handle to identify the target port. The device handle is only valid in the context of the API. Do not use the device handle with WIN32 API calls that accept object handles.

A list of available ports is obtained with MgslEnumeratePorts. This call returns an array of MGSL_PORT structures that provide the port identifier, adapter type, and device name for each available port. The adapter type and device name can be used for display purposes when prompting the user for a port selection.

The port ID is a 32-bit value that identifies both an adapter and a port on an adapter. The upper 16 bits is the port number, and the lower 16 bits is the adapter number. The MGSL_GET_ADAPTER() macro returns the adapter number of a port ID. MGSL_GET_PORT() returns the port number of a port ID. MGSL_MAKE_PORT_ID() creates a port ID from an adapter and port number. Single port adapters always have a port number of 0, so the port ID is the same as the adapter number. Multiport adapters have port numbers starting with 1 up to the number of ports on the adapter.

Port names for single port adapters have the form 'MGHDLCx', where 'x' is the adapter number. Port names for multiport adapters have the form 'MGMPxPn', where x is the adapter number and 'n' is the port number. Adapter numbers are assigned automatically when the adapter is installed.

An application with integrated tracing uses the handle returned by MgslOpen with the API tracing functions. An external tracing application, such as the trace utility, calls MgslOpenTraceHandle . This returns a port handle even if an application already has an open handle to the same port obtained with MgslOpen. Calling MgslOpenTraceHandle requires administrative privilege. A trace handle is valid for all API calls, but should be used only with tracing functions.