# NDIS Implementation Information
for IBM LAN Systems
OS/2 Messaging and National Language Support

## Table of Contents

- About This Document

- 1.0 General Strategy

- 2.0 Standardized Services for Device Driver Message Display and Logging
- 2.1 Device Driver Initialization
  - 2.1.1 Implementation
  - 2.1.2 Functions Provided
    - 2.1.2.1 Function 01: Message Service Request
    - 2.1.2.2 Function 02: Message IDC Information Request
    - 2.1.2.3 Function 03: Combine Functions 01 and 02
    - 2.1.2.4 Function 07: Request Default Path
  - 2.1.3 Calling Conventions and Input Parameters for the DosDevIOCtl Entry Point
  - 2.1.4 Example DevIOCtl
- 2.2 Device Driver Strategy Time
  - 2.2.1 Implementation
  - 2.2.2 Calling Conventions and Input Parameters for the IDC Entry Point
  - 2.2.3 IDC Entry Example

- 3.0 Non-Device Interface to the LAN Transport Message Functions
- 3.1 Functional Description
- 3.2 Implementation
  - 3.2.1 Input Parameters
  - 3.2.2 Calling Conventions
    - 3.2.2.1 Linking Method:
    - 3.2.2.2 Parameter Passing on Calling Sequence

- 4.0 Data Structure Definitions and Return Codes
- 4.1 Message Parameter Block
- 4.2 DevIOCtl Returned Status Field: (DevIOClt Function 1)
- 4.3 IDCInformation Request Packet: (DevlOCtl Function's 2 & 3)
- 4.4 Default Path Information Request Packet: (DevlOCtl Function 7)
- 4.5 Possible Return Codes

- 5.0 Installation/Configuration
- 5.1 CONFIG.SYS Entries
- 5.2 Configuring the Override for the Default Path Name
  - 5.2.1 Search Path Rules
- 5.3 Other Configuration Parameters to the Messaging Support Driver

- Notices
  - Copyrights
  - Disclaimers
  - Trademarks

[next][parent][TOC]

## About This Document

This document describes the interface for device drivers ring-3 application, and information about the specific implementation as it pertains to the message strategy of and National Language Support (NLS) for an IBM* Network Driver Interface Specification (NDIS) 2.01 device driver, as implemented in IBM* LAN Adapter and Protocol Support*. This document is not meant to be a tutorial; it is assumed that the user has knowledge of the rules and procedures on calls made to device drivers using both the DosDevlOCtl interface and the InterDevice Driver Communications (IDC) entry point. The information on these topics is presented here in a reference or summary manner.

Note: NDIS 2.0.1 is jointly authored by the 3Com*** Corporation and the Microsoft** Corporation.

The following publications provide additional information:

- 3Com/Microsoft LAN Manager** Network Driver Interface Specification (NDlS), Version 2.0.1, October 8, 1990
- Microsoft LAN Manager, Programmer's Guide for NDIS, Version 2.0. 1, June, 1990
- NDIS Implementation Information for IBM LAN Systems, Extended NIF Format, May, 1993
- NDIS implementation Information for IBM LAN Systems, NDIS Extensions, May, 1993

[previous][next][parent][TOC]

## 1.0 General Strategy

- All messages will be kept in a file separate from the application. They are separated from the executable code to enable NLS translation of messages into different languages without altering the calling program. It is strongly recommended that a help message file be included as a companion for the message file.
  Refer to the OS/2 Technical Reference for the format of message text and the output file of MKMSGF utility.
- When errors are encountered by an NDIS driver during the IPLing of the machine, a message describing the error should be logged into a message log file and displayed to the console.
- If the LAN message device driver (LANMSGDD.OS2) is installed, and its companion DLL file (LANMSGDL.DLL) is available, then messages describing any errors can be logged in the message log file (LANMSGDD.LOG) and displayed to the console. This message log display interface is compatible with First Failure Support Technology/2 (FFST/2) and can be used at both IPL and run time.
  The detailed LAN message device driver interface is described in Chapter 2, and the interface for ring-3 applications is described in Chapter 3.
- The message and log files are assumed to be in the \IBMCOM subdirectory, unless changed by the user.

[previous][next][parent][TOC]

## 2.0 Standardized Services for Device Driver Message Display and Logging

This section describes the input parameters and calling conventions for the LAN message device driver (LANMSGDD.OS2). This piece of the system runs at privilege level zero and can be accessed by other device drivers both during their initialization and strategy lifetime. The interface basically enables a message to be retrieved from an NLS translatable message file and written to a message log file, and optionally displayed to the console. This means ring-0 message logging is now possible. The intent of this ring-0 service is not to enforce a standardization upon device drivers needing messaging service but rather to offer an interface that facilitates problem solving at the device driver or system level.

The interface is written to be compatible with the First Failure Support Technology/2 (FFST/2) interface but will still provide messaging services if FFST/2 is not available on the system. Thus, some parameters that may seem redundant for an application running with ring-3 privilege level are nevertheless required input to FFST/2.

[previous][next][parent][TOC]

## 2.1 Device Driver Initialization

During a device driver initialization period, it runs as a pseudo ring-3 application. During this time, it has access to a subset of DOS calls, including DosOpen, DosWrite, DosGetMessage and DosPutMessage. Using these APIs at initialization time, a device driver can display and write its messages to a log without assistance. This is the method most device drivers are currently using. However, this ability is lost after the device completes initialization.

A ring-3 entry point to the messaging support driver is provided solely for the sake of standardization and convenience to the device drivers it services. It exists so that all messages in a system can be logged to the same file without requiring knowledge about the log file name or location. It also alleviates the need for a device driver to open, go to the end of the file, write the record, and close the file for every message logged. Thus, this ring-3 interface can eliminate redundant code that would otherwise be needed in each device driver.

In order for messaging services to be available to other device drivers at IPL time, it is required that the LANMSGDD.OS2 module load prior to the calling device. This is easily accomplished by placing the DEVICE= statement for LANMSGDD.OS2 before the calling device in CONFIG.SYS. This ensures that when a device driver enters it initialization period, the messaging support driver is already loaded. As such, the messaging support driver has already made its transition from ring-3 to ring-0. The DOS services to which the initializing device driver has access are now unavailable to the messaging support driver. Its only access to these functions is through its ring-3 thread started by LANMSGEX.EXE. This thread, however, is not available until all device drivers specified in CONFIG.SYS have completed loading. To handle this, LANMSGDD.OS2 uses a queue for incoming message requests until the ring-3 thread is ready.

When the messaging support driver is called, it queues the request until the ring-3 services provided by LANMSGDL.DLL are available. For message logging, this is not a problem since the user cannot view the log until after IPL. However, messages that are to be displayed to the console during device driver initialization will experience a delay until the queue is processed. Therefore, if a device driver has a banner or logo it wants displayed during its initialization period, it may be preferable to use an API such as DosWrite to generate standard output.

[previous][next][parent][TOC]

### 2.1.1 Implementation

The messaging support driver ring-3 entry point is implemented using a general DosDevIOCtl call. Before DosDevIOCtl call can be made, the calling device driver will need a file handle by issuing a DosOpen to the messaging device driver. The name to use on the DosOpen call is \LANMSG$$. Even though it is not currently required, it is suggested that the full path and file name, \DEV\LANMSG$$, be used on the DosOpen. There was once an OS/2 1.2 requirement that the \DEV path be used to open a device driver. This requirement was dropped, but use of the path does work and it may prevent a code modification in some future release.

[previous][next][parent][TOC]

### 2.1.2 Functions Provided

Several messaging functions are provided to device driver applications when they run at privilege-level 3. To invoke these functions, the DosDevIOCtl function category 90h (the message device category code) must be used. This category will generate a general DevIOCtl to the messaging support driver. Four message service requests are provided through this category depending upon the DosDevIOCtl function code passed. The functions provided are:

            Function 01 = Request messaging services.
            Function 02 = Request LANMSGDD IDC entry point.
            Function 03 = Combine requests 01 and 02 in one DevIOCtl call.
            Function 07 = Request Default Message Path.

[previous][next][parent][TOC]

#### 2.1.2.1 Function 01: Message Service Request

Function 01 will generate a general request for messaging services. The specifics of the request are contained in the input parameters passed in the DosDevIOCtl parameter buffer. This field is a far pointer (DWORD) to the message parameter block. This parameter block contains the component name of the device driver requesting services, the message number to access, the type of message, a display option, the full path and file name of the message input file, the output log file, and any insertion strings required for the message. A detailed description of the message parameter block is contained in 4.0, "Data Structure Definitions and Return Codes". The only required input parameter in the message parameter block is the message number identifier. All others are optional.

Output parameters are passed back to the calling routine in the DosDevIOCtl data buffer field. This field is a far pointer (DWORD) to a status variable. This variable is a WORD and will contain the return code on the success of the request. This field is needed since AX will contain the return code of the DosDevIOCtl call itself and is required on all message DosDevIOCtl calls. Device driver return codes are detailed in 4.0, "Data Structure Definitions and Retum Codes".

[previous][next][parent][TOC]

#### 2.1.2.2 Function 02: Message IDC Information Request

This function allows a device driver to gain access to the message device driver ring-0 protect mode code segment entry point and data segment. This function alleviates the need for a device driver to issue an AttachDD during its ring-0 strategy time. It is important to remember that although one has the ring-0 entry point at its initialization time, a device driver may not use it until it has made its ring-0 transition.

There are no input parameters other than the function code passed on the DosDevIOCtl. Thus, the DosDevIOCtl parameter buffer field is null. Output is passed back in the data buffer area of the DosDevIOCtl. The data buffer must point the IDC information request packet. The first WORD of the packet contains the required status of the request. This is followed by a DOUBLE WORD, which contains the code segment and offset of the message device driver ring-0 entry point. The last field is a WORD, which contains the data segment of the Messaging Support Driver. A description of the IDC information request packet is contained in 4.0, "Data Structure Definitions and Return Codes" .

[previous][next][parent][TOC]

#### 2.1.2.3 Function 03: Combine Functions 01 and 02

This function is provide solely for the convenience of the calling device driver. It keeps the caller from having to make two separate IOCtl's. Required input and output parameters for this function are a combination of functions 01 and 02. The parameter field points to the message parameter Block and the Data field points to the IDC Information Request Packet.

[previous][next][parent][TOC]

#### 2.1.2.4 Function 07: Request Default Path

There is a hard-coded path where the messaging support driver (LANMSGDD.OS2) expects to find the default input message file, LT0.MSG, and will create the default output file, LANTRAN.LOG. This default path is \IBMCOM. Although the names of the default message file and log files usually do not need to be changed, they can be overridden using the input parameters passed in the message parameter block. The default path can be overridden using an input parameter on the DEVICE = statement for LANMSGDD.OS2 in CONFIG.SYS. This function is provided to enable device drivers to access the current default path. Refer to 5.0, "Installation/Configuration" for details.

Like Function 02, this function has no input parameter except the DosDevIOCtl function number itself. The DosDevIOCtl parameter buffer field is, therefore, null. The output of the request, like the other functions, is resumed through the DosDevIOCtl data field which points to the default path information request packet. The first WORD of the packet contains the status of this request. The next field in the packet contains a 32-bit pointer to a buffer where it will copy the full path and filename. Even though the default file name, LT0.MSG, can not be changed, the message device driver returns the full path and file name of the default message file. The next WORD in the packet holds the length of the path portion of the name only. Currently the maximum path length that the messaging support driver uses is 250 bytes.

The usefulness of this function lies in its ability to allow applications that do not use the default message file to query the messaging support device driver to obtain the current default path. This path is where the device driver can expect to find its message file. The application can then replace the default message file name with its own message file name. Accordingly, applications can keep their own message and log files in a common directory other than \IBMCOM. It may also prevent a device driver from having to define its own input parameter for the same purpose.

[previous][next][parent][TOC]

### 2.1.3 Calling Conventions and Input Parameters for the DosDevIOCtl Entry Point

                              (OS/2 creates a general DevIOCtl)

    Function category:  90h = Message device category code.

    Function code:      01  = Request messaging services.
                              02 = Request LANMSGDD IDC entry point.
                              03 = Combine request 01 and 02 in
                                   one DevIOCtl call.
                              07 = Request default path. Location of
                                   the default message (LT0.MSG)
                                   and log file (LANTRAN.LOG).

    Parameter Buffer:  Far pointer to the message parameter
                             block. (This structure is defined
                             below.)

    Data Buffer:       Far pointer to the IDC information
                             request packet, default path
                             request packet, status variable.
                             (These structures are defined below.)
                             The status field in these structures
                             contain the return code for the
                             request. If function 01, messaging
                             services, is requested, only the status
                             field is required.

[previous][next][parent][TOC]

### 2.1.4 Example DevIOCtl

Note: On a DosDevIOCtl, a DosOpen is first required on the device driver name, LANMSG$$, to obtain a handle. This handle is used as input on the DosDevIOCtl call.

    push	DS              	;	Pass address if data packet,
    push	OFFSET Msg_Status	;	  offset to status field
    push	ds              	;	PASS PARMLIST , offset to
    push	OFFSET Msg_Params	;	  message parameter block.
    push	1                	;	Function code (message request)
    push	90h             	;	Messaging category
    push	Msg_DDHand      	;	Handle to LANMSG$$ from DosOpen.
    call    DOSDEVIOCTL
    cmp     Ax,0            	;	DevIOCTL SUCCESS?
    jne     Out_Err         	;	No.
    cmp     Msg_Status,0    	;	Message request successful?
    jne     Out_Err         	;	No.

[previous][next][parent][TOC]

## 2.2 Device Driver Strategy Time

The ring-0 interface (IDC or device driver strategy entry point) can be obtained using an AttachDD call or through a DevIOCtl, function 2 or 3, call during a device driver initialization.

[previous][next][parent][TOC]

### 2.2.1 Implementation

Calls to this entry point give a device driver access to the general messaging services provided by the messaging support driver. This entry point provides the equivalent functionality as that obtained the DosDevIOCtl function 02 call. Once the IDC entry point is obtained, only two parameters are required. The first parameter is a WORD value of 1. This value signifies that a device driver is requesting messaging services. The second parameter is a far (32-bit) pointer to the message parameter block. This is the same input block passed in the parameter buffer on the DosDevIOCtl call for function 02. Finally, AX will contain the same returned status code as that recorded in the data buffer Area of the function 02 DosDevIOCtl call.

[previous][next][parent][TOC]

### 2.2.2 Calling Conventions and Input Parameters for the IDC Entry Point

A list of the IDC, (inter-device communication or ring-0) input parameters and return code follow:

    IDC invocation code:        0x0001 = Messaging function code.

    Message parameter block:	A far pointer to the message parameter
                                      block
    Return code:	            On return, AX  contains the same code
                                      as that logged in the IOCTL status
                                      field located in the DevIOCTL's data
                                      buffer Area.

[previous][next][parent][TOC]

### 2.2.3 IDC Entry Example

Note: If a DosDevIOCTl requesting the message device driver IDC entry point was not issued, an ATTACHDD is first required to get it. The calling application is also required to establish LANMSGDD DS before the call.

    push	es                  	;	PASS PARMLIST, offset to
    push	OFFSET Msg_Params    	;	   message parameter block.
    push	1                   	;	Pass message IDC invocation.
    call	DWORD ptr es:"Msg_CS"	;	Call the MessageDD
    cmp     AX,0                	;	Success?
    jne     OutMsg_Err           	;	No.

Note: When calling to the IDC entry point, the calling routine is assumed to have set up LANMSGDD data selector into DS prior to the call.

[previous][next][parent][TOC]

## 3.0 Non-Device Interface to the LAN Transport Message Functions

Following are a functional description and an implementation of the non-device interface to the message functions.

[previous][next][parent][TOC]

## 3.1 Functional Description

An additional entry point into the LAN transport message services has been defined using a dynamic link library (DLL). This entry point is available only after device driver initialization at IPL time. A ring-3 thread holds the DLL in memory for quick access to the entry point. The file itself is LANMSGDL.DLL, and its thread is LANMSGEX.EXE. Functionally, this entry point (MRMSG) provides access to the same general messaging services as those provided by both the DevIOCtl Function 01 entry and the IDC entry. In fact, a ring-3 application could call the messaging support device driver DevIOCtl entry and thereby gain access to all of its defined IOCtl functions. This interface provides a more direct access to the messaging function and is implemented solely for the convenience of an application.

[previous][next][parent][TOC]

## 3.2 Implementation

The non-device driver entry point is provided for ring-3 applications as a direct interface into the message dynamic link routine, LANMSGDL.DLL. It is not dependent upon the messaging support driver or its ring-3 EXE file, LANMSGEX.EXE, for existence. It operates like any DLL, from the thread of the calling routine. Actually, it is the same interface the LANMSGEX.EXE routine uses to output its own messages. It has been externalized for the convenience of any ring-3 application wanting to use it.

The message DLL routine contains all the logic for outputting a message to the console/log file or to FFST/2. This routine also determines if FFST/2 is present and available. It reformats the input parameters according to the interface being accessed. If FFST/2 is installed but not initialized, a warning message is displayed and logged, but no further attempt is made to access FFST/2 until the next IPL.

[previous][next][parent][TOC]

### 3.2.1 Input Parameters

Input to the routine is very similar to the IDC entry point parameters. Its first input parameter is a FAR pointer to the same message parameter block defined for the other two interfaces. See the description of the message parameter block in 4.0, "Data Structure Definitions and Return Codes". The second parameter is a WORD value that acts as an FFST/2 option flag. It allows an application to specify whether output to FFST/2 is desired. If the value passed is zero, the DLL precludes the use of the FFST/2 interface. If the value is set to 1, the routine uses FFST/2 services if they are available. The final parameter is a DWORD and is reserved. As such it must be 0. A list of the input parameters follows:

    Message parameter block:	A far pointer to the message parameter block.
    FFST/2 Options Flag:        0x0000 = Do not use FFST/2
                                    0x0001 = Use FFST/2 interface if available.
    Reserved:	                DWORD value of all 0's.

[previous][next][parent][TOC]

### 3.2.2 Calling Conventions

The entry point label name to the Non-DD ring-3 interface is MRMSG. Either of the following OS/2 DLL linking methods can be used to gain access to this entry point. Each method for linking to MRMSG is demonstrated.

[previous][next][parent][TOC]

#### 3.2.2.1 Linking Method:

This first example has only a requirement to include an IMPORT statement for LANMSGDL.MRMSG in the link deflation file.

Example - Method 1:

    MASM external reference in source program:
      EXTRN MRMSG : FAR ; DLL message output routine.
    Linking example:
      LINK Appl.OBJ,Appl.exe,,Appl.MAP,doscalls,Appl.DEF /NOD/NOT/MAP;

    Example OS/2 definition file:
     NAME APPL WINDOWCOMPAT
     PROTMODE
     DESCRIPTION 'APPL ANY RING-3 APPLICATION'
     STACKSIZE 4096
     IMPORTS
      LANMSGDL.MRMSG

The second method does not require any external reference definitions or DEPORT definition. It makes use of OS/2 DosLoadModule and DosGetProcAddr. For a discussion of this method see the 0S/2 Programmer's Reference. A sample of this method follows.

Example Method 2:

    ;;; 	Now load DLL module
    push	SEG  ObjBuf 	;Addr to buffer for the failing module
    push	OFFSET ObjBuf
    push	ObjLen      	;Above's buffer length
    push	SEG LanMSgMod	;Pointer to module name 'LAMSGDL'
    push	OFFSET LanMsgMod
    push	Seg LanMsgHand	;Pointer to word value for Handle
    push	OFFSET LanMsgHand
    call	DosLOADMODULE
    or  	ax,ax
    jnz     Error_End   	;Bad return; cannot call module

    ;;;	Now get module entry point

    push	LanMsgHand  	;Handle to DLL module
    push	SEG LanMsgProc	;Pointer to procedure name 'MRMSG'
    push	OFFSET LanMSGProc
    push	SEG MRMSG   	;Ptr to DWORD to contain entry point
    push	OFFSET MRMSG
    call	DOSGETPROCADDR
    or  	ax,ax
    jnz  	Error_End   	;Bad RC; do not call module

[previous][next][parent][TOC]

#### 3.2.2.2 Parameter Passing on Calling Sequence

An example of the calling sequence to the MRMSG interface follows:

    ;;;;	Call message DLL here
    push	SEG MsgData	; Pass msg control block
    push	OFFSET MsgData
    push	1       	; Use FFST/2 if available
    push	0       	; First WORD of 0'st
    push	0       	; Second WORD of 0's
    call	MRMSG    	; Far call to output msg
    or   	ax,ax   	; Error?
    jne     Error_End	; Yes.

[previous][next][parent][TOC]

## 4.0 Data Structure Definitions and Return Codes

Data structure definitions are provided for the message parameter block, the DevIOCtl resumed status field, the IDC information request packet, and the default path information packet. Return codes are also listed.

[previous][next][parent][TOC]

## 4.1 Message Parameter Block

The message parameter block is the basic input parameter structure used to request messaging services using both the DevIOCtl and the IDC entry points for device drivers and the non-device driver entry point for ring-3 applications. It is composed of the following fields (in order).

- COMPONENT_ID - Far pointer (double word) to an 8-byte string that identifies the calling component, for example, the name of the device driver requesting messaging services. If null, the message contains information about who originated the message. If FFST/2 is installed, this field is used as the subcomponent name. (OPTIONAL)
- IV_ ARRAY - Far pointer to an array of far pointers, from 0-9, that point to a 0-terminated string text used as message text insertion data. (If null, no insertion data exists.) (OPTIONAL)
- IV_Number - Word value indicating the number of text insertion pointers found in the IV_Array field. Values 0 - 9 (0 means no insertion data exists). (OPTIONAL)
- MESSAGE_Num - Word value used to hold the message number ID of the desired message. (REQUIRED)
- Message_File - Far pointer to a null-terminated string identifying the path and message file name that contains the message text. If null, the default is used. (OPTIONAL)
- Message_Type - Afford value used for the following types. (OPTIONAL)

                         4500h - ('E'00) denotes an error message.
                         5700h - ('W'00) denotes a warning message.
                         4900h - ('I'00) denotes an informational message.
                         0000h - (''00) denotes an unclassified message.

- Display_Flag - Word value indicating the console display option. (OPTIONAL)

                      Possible values include:
                          False (0) - do not display, even if error type.
                          True (1) - display to console.

- Log_File - Far pointer to an alternate message log path and file name where the messages will be written. If null, the default is used. (OPTIONAL)

[previous][next][parent][TOC]

## 4.2 DevIOCtl Returned Status Field: (DevIOClt Function 1)

When requesting message services of DosDevIOCtl function 1 to the message device driver, the data buffer field on the IOCTL call must point to a WORD value. This value contains the status of the request on IOCTL completion. This status field is required on all DevIOCtl calls to the messaging device driver.

    Returned status of request - Word (REQUIRED for all DevIOCtl's)

[previous][next][parent][TOC]

## 4.3 IDC Information Request Packet: (DevIOCtl Function's 2 & 3)

The ring-0 Information Request Packet is used for DevIOCtl output, i.e., passed in the Data Buffer area on the DosDevIOCtl call. The packet's structure is defined below:

    Returned status of request - Word (REQUIRED for all DevIOCtl's)
    IDC/ring-0 entry point     - Double word (REQUIRED for IOCTL functions 2 and 3)
    Ring-0 data segment        - Word (REQUIRED for IOCTL functions 2 and 3)

[previous][next][parent][TOC]

## 4.4 Default Path Information Request Packet: (DevIOCtl Function 7)

The ring-0 path information request packet can be used to determine what the current default message path is. The packet is used as output, that is, output passed in the data buffer area on the DosDevIOCtl call. The request packet is defined as follows:

    Returned status of request  - Word (REQUIRED)
    Default path buffer address - Double word pointer (REQUIRED)
    Length of path name         - Word (REQUIRED)

[previous][next][parent][TOC]

## 4.5 Possible Return Codes

Possible return codes for all message entry points follow.

Note: This list is not intended to be exhaustive. Other unexpected DevHelp or OS/2 system calls may also be received.

    0x0000 - Request has been accepted.
    0x0001 - ERROR INVALID FUNCTION (Bad IDC invocation)
    0x0002 - ERROR FILE NOT FOUND
    0x0008 - ERROR NOT ENOUGH_MEMORY (Not enough internal resources
             to satisfy request)
    0x013C - ERROR MR_MSG_TOO_LONG (Message too long for message buffer)
    0x013D - ERROR MR_MID_NOT_FOUND (Message number not found)
    0x013E - ERROR MR_UN_ ACC_MSGT (Unable to access message file)
    0x013F - ERROR MR_INV_MSGT_FORMAT (Invalid message file format)
    0x0140 - ERROR_MR_INV_IVCOUNT (Invalid insertion variable count)
    0x0141 - ERROR_MR_UN_PERFORM (Unable to perform function)

[previous][next][parent][TOC]

## 5.0 Installation/Configuration

There are three separate modules required for messaging services. The ring-0 executable filename of the device driver is LANMSGDD.OS2. The device driver maintains a detached ring-3 thread, which it uses to gain access to DOS kernel services. The ring-3 executable file name is LANMSGEX.EXE. This ring-3 thread also requires the ring-3 message DLL file LANMSGDL.DLL

[previous][next][parent][TOC]

## 5.1 CONFIG.SYS Entries

The messaging device driver is loaded by a DEVICE = statement in the CONFIG.SYS file. This statement should be inserted into the CONFIG.SYS before any other LAN related device driver statements.

In order to provide the detached ring-3 thread, a RUN = statement for the LANMSGEX.EXE file is a so required. Additionally, in order to gain access to the messaging DLL file, a path name where the LANMSGDL.DLL exists must be entered on the LIBPATH statement in the CONFIG.SYS file.

Assuming the Lan Transport Services reside in the \IBMCOM subdirectory, the entries in CONFIG.SYS should be the following:

    LIBPATH=C:\OS2\DLL;C:\IBMCOM;
    .
    .
    .
    DEVICE=C:\IBMCOM\LANMSGDD.OS2
    RUN=C:\IBMCOM\LANMSGEX.EXE

[previous][next][parent][TOC]

## 5.2 Configuring the Override for the Default Path Name

The default path where the messaging support driver expects to find the message file and where it will place the log file is the IBMCOM directory. The default path can be overridden by placing an optional /I parameter on the LANMSGDD's DEVICE = statement in the CONFIG.SYS file. An example follows:

    DEVICE=C:\IBMCOM\LANMSGDD.0S2 /I :C:\IBMLAN

The /I parameter requires the drive and directory where the message file and message log reside. A terminating backlash on the override string must not be included. If the drive is omitted, the current root is assumed.

The default message and log file names are LT0.MSG and LANTRAN.LOG. These defaults can be overridden only by using the runtime interface input parameters to the messaging support driver. If the C:\IBMCOM default is desired, the /I parameter can be omitted.

[previous][next][parent][TOC]

### 5.2.1 Search Path Rules

Rules for message and log file search paths follow:

1. If the message file does not exist in the default path but the path exists, the device driver searches the root directory for the input message file but still logs all messages using the original default path.
2. If the default path does not exist, the root directory is searched for the message file. If found, the default path is changed to the root and the log file is also placed there.
3. If the message file cannot be found in the default or the root directory, the device driver fails to install, and the log file is created in the root directory.

[previous][next][parent][TOC]

## 5.3 Other Configuration Parameters to the Messaging Support Driver

There are two other parameters which can effect the messaging support driver functioning. Like the default path override, these too are placed on the DEVICE = statement of the LanMsgDD device driver. The /S parameter disables the display function, while the /P disables the pause-on-error function.

If the customer wants to disable all messaging display from the messaging support driver, the /S parameter can be inserted at the end of the DEVICE= statement for LANMSGDD.OS2 in the CONFIG.SYS file. This will not affect messages that are displayed independently by a device driver at initialization time but will disable any message sent to the messaging support driver with the display option on. The messages will continued to be logged.

Currently if a message is received by the messaging support driver with an error type set and the display option on, the message is displayed and with a pause-on-error message. This pause-on-error requires operator intervention to continue. By default the pause-on-error option is on. To disable pause-on-error in the messaging support driver, the /P option can be inserted at the end of the DEVICE= statement for LANMSGDD.OS2 in CONFIG.SYS.

These parameters can be inserted in any order and may be entered in either upper or lower case.

[previous][next][parent][TOC]

## Notices

May, 1993

Issued by:

IBM Corporation
Personal Software Products
11400 Burnet Road
Austin, Texas 78758

First Edition (May 1992)

Second Edition (May 1993)

The following paragraph does not apply to the United Kingdom or any country where such provisions are inconsistent with local law: INTERNATIONAL BUSINESS MACHINES CORPORATION PROVIDES THIS PUBLICATION "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. Some states do not allow disclaimer of express or implied warranties in certain transactions, therefore, this statement may not apply to you.

This publication could include technical inaccuracies or typographical errors. Changes are periodically made to the information herein; these changes will be incorporated in new editions of the publication. IBM may make improvements and/or changes in the product(s) and/or program(s) described in this publication at any time.

It is possible that this publication may contain reference to, or information about, IBM products (machines and programs), programming, or services that are not announced in your country. Such references or information must not be construed to mean that IBM intends to announce such IBM products, programming, or services in your country.

[previous][next][parent][TOC]

### Copyright Notices

© Copyright International Business Machines Corporation 1992, 1993. All rights reserved.

Note to U.S. Government Users - Documentation related to restricted rights - Use, duplication or disclosure is subject to restrictions set forth in GSA ADP Schedule Contract with IBM Corp.

[previous][next][parent][TOC]

### Disclaimers

References in this publication to IBM products, programs, or services do not imply that IBM intends to make these available in all countries in which IBM operates. Any reference to an IBM product, program, or service is not intended to state or imply that only IBM's product, program, or service may be used. Any functionally equivalent product, program, or service that does not infringe any of IBM's intellectual property rights or other legally protectible rights may be used instead of the IBM product, program, or service. Evaluation and verification of operation in conjunction with other products, programs, or services, except those expressly designated by IBM, are the user's responsibility.

IBM may have patents or pending patent applications covering subject matter in this document. The furnishing of this document does not give you any license to these patents. You can send license inquiries, in writing, to the IBM Director of Commercial Relations, IBM Corporation, Purchase, NY 10577.

[previous][next][parent][TOC]

### Trademarks

The following terms, denoted by an asterisk (*) in this publication, are trademarks of the IBM Corporation in the United States and/or other countries:

IBM | OS/2

The following terms, denoted by a double asterisk (**) in this publication, are trademarks of other companies as follows:

3Com | 3Com Corporation
Microsoft LAN Manager | Microsoft Corporation