OS/2 Considerations

This section summarizes information for developing LUA applications on OS/2.

This implementation of LUA is binary-compatible with the implementation of the RUI and SLI interfaces in IBM Extended Services (ES) for OS/2 version 1.0 LUA. Therefore, there are no migration steps for IBM ES for OS/2 version 1.0 applications. However, if you recompile an IBM ES for OS/2 version 1.0 LUA application for use with LUA, include the WINLUA.H header file provided in the SNA Server Software Development Kit to ensure complete platform compatibility.

Note that this LUA implementation does not support user-defined encryption and decryption routines.

Critical sections

Exercise great caution when using critical sections, which are the parts of a program that must run without interruption. An application must not issue an LUA verb within a critical section.

Data segments

Data is sent from and received in data buffers established by the application. A data buffer must reside on an unnamed shared data segment and must fit entirely within the data segment. Many data buffers can reside on the same data segment.

The data segment for the VCB must have read and write attributes. It can be one of the following:

• A variable (not a local variable because LUA will copy data to it on completion of the verb).
• Allocated dynamically using DosAllocSeg or DosSubAlloc.

Load-time linking

For an application to be dynamically linked to LUA at load time, you must do one of the following at link time:

• Insert the following IMPORTS statement in the definition (.DEF) file used to link the application:

  (For RUI)

  IMPORTS RUI.RUI
   

  (For SLI)

  IMPORTS SLI.SLI
   

• Link the application to ACSRUI.LIB (for RUI) or ACSSLI.LIB (for SLI), which contain the entry-point linkage information for various APIs.

Multiple threads

An application session can have multiple threads that issue verbs. However, the same thread of an application cannot issue two verbs simultaneously. If LUA is executing a verb and the same thread of the application issues a verb, LUA returns the lua_unsuccessful return code to the later verb and leaves it unexecuted.

OS/2 exception TRAP 000D

The OS/2 exception TRAP 000D is issued when LUA is unable to pass a return code to the application for one of the following reasons:

• The data segment containing the VCB is not read/writable.
• The VCB is fewer than 10 bytes in length.
• The semaphore supplied through the lua_post_handle parameter is neither a valid RAM or OS/2 system semaphore nor a pointer to a location within a writable segment.

Packing

VCBs are not packed. As a result, DWORDs and WORDs are on WORD boundaries, and BYTEs are on BYTE boundaries. This means, for example, that there is not a 2-byte gap between the primary and secondary return codes. VCBs should be accessed using the structures provided, and compiler options that change this packing method should be avoided.

Process support

A single RUI or SLI LU can be used by only a single process. A single process can act as multiple RUI/SLI applications and have sessions using multiple LUs.

Run-time linking

For an application to be dynamically linked to LUA at run time, it must issue the following calls:

• Call the DosLoadModule function to dynamically load the ACSRUI.DLL (for RUI) or ACSSLI.DLL (for SLI) library module for LUA.
• Call the DosGetProcAddr function to set the entry point RUI or SLI to the dynamic-link library.

Unlinking (the DosFreeModule call) is not supported.

Simultaneous sessions

An application can participate simultaneously in as many as 512 sessions per OS/2 process.

Stack size

The recommended stack size for an application is at least 3000 bytes.

When executing a verb, LUA uses the calling application's stack. The combination of OS/2 and LUA requires 2560 bytes of stack space, and the application requires additional stack space for its variables.

VCB segment

The segment containing the VCB must be a writable segment. All reserved and unused fields in the VCB should be set to 0x00.