This section describes how OS/2 function calls are issued. OS/2 applications must use the dynamic link mechanism (FAR CALL) to get to all services. The old style (INT 21 H ... )function calls are supported only for the DOS mode.
OS/2 Function Call Rules
Rules for the OS/2 interface are shown below:
Rule 1: All parameters are passed on the stack (SS:SP).
Remarks Passing parameters on the stack is consistent across a broad base of languages on the 80286 family of
processors. This method allows direct access to the oper-ating system from high order languages. The minimum recommended stack space available is 2K bytes.
Rule 2: All interfaces pass a return code back to the caller in AX.
Remarks The use of register AX as a function return code is also consistent across many languages. All user registers except the FLAGS register are preserved. The contents of the FLAGS register are undefined. The state of the tion flag in the FLAGS register is preserved. If the direc-tion flag was clear when an API was called then it will be clear when the API returns.
Rule 3: All addresses of OUTPUT parameters are of the form:
selector: offset.
Remarks Fully qualified addresses are available across all memory models as a method for returning values to a requester.
This allows one function entry point to serve all languages and memory models.
Rule4: Each function is accessed by a FAR CALL.
Remarks This is a requirement for the functions to be dynamic link entries.
Rules: All functions remove the parameters from the stack.
Remarks Parameter lists are fixed length on a function basis. Vari-able length parameter lists are not supported.
Rule 6: All function names must be upper case at link time.
Remarks If a compiler or assembler generates case-sensitive (upper and lower case) external references, all calls or function definitions must be in all UPPER case characters.
OS/2 Function Call Characteristics
The function call descriptions follow a pseudo assembly language format. The interfaces are shown to be descriptive rather than to be an example of a coding sequence. The conventions described below are employed throughout this book.
Function Call Format
Because all parameters are pushed onto the stack, there are several pseudo instructions to describe these operations.
• PUSH - push an item onto the stack
This can be used to push various size items onto the stack. The data item types are described below.
• PUSH@ - push the address of an item onto the stack
All addresses in these interfaces are composed of a 32-bit value:
a 16-bit selector, and a 16-bit offset. This address can point to any of the data item types.
• CALL - call a function
All function calls are accessed via FAR CALLs. This is a require-ment to utilize the Dynamic Link mechanism.
The following are data item types used to make up a parameter list:
• WORD - 2 bytes
This type of operand can be passed by value (pushed onto the stack) or by reference (the address of the operand is passed on the stack).
• DWORD - 4 bytes
This type of operand can be passed by value (pushed onto the stack) or by reference (the address of the operand is passed on the stack).
• ASCllZ - null (0) terminated character string
This type of operand can be accessed only by reference.
• Other - any other structure
This type of operand can be accessed only by reference.
Interface Stack Frame
All parameters are passed via the stack. An example stack frame is shown below:
The following is the calling sequence that corresponds to the diagram above.
Function Calling Sequence Example
This is a sample function call. In Technical Reference, Vol. 2, the function calling sequence is shown using pseudo code. The pseudo code is similar to IBM Personal Computer Macro Assembler. Some definitions and necessary statements for segments and procedures are left out. The following example shows how a function call builds a stack and also how the pseudo code relates to actual code.
Pseudo Code
extrn DOSXAMPL:far
PUSH WORD INl PUSH@ WORD OUTl
PUSH WORD IN2
CALL DOSXAMPL
Actual Code
extrn DOSXAMPL:far
these items are in OS INl
IN2 OUTl
push INl push ds
dw db dw
44
•x•
a
mov ax.offset OUTl push ax
mov al,IN2 xor ah,ah push ax call DOSXAMPL
OS/2 Sample Functions
The following are sample functions. The code indicated is similar to IBM Personal Computer Macro Assembler. Some definitions and necessary statements for segments and procedures are left out.
Function DOSXAMPL
This is an example function that retrieves information from a stack. It shows entry and exit sequences for a function and how to access the parameters.
push bp mov bp,sp
les bx,[bp+8] get the@ of OUTl mov word ptr es:[bx],77 ; put 77 in OUTl mov ax,[bp+12] put INl in ax mov bl,[bp+6] put IN2 in bl
mov ax,17 set the return code to 17 pop bp
ret (far) 8 remove parameters from stack and return
High-Level Language Interface Examples
These are examples of high-level language interfaces for the "OS/2 Sample Functions" on page 2-8 and the "Function Calling Sequence Example" oh page 2-7.
IBM Pascal Compller/2™2: This is an example of the interface used with the IBM Pascal Compiler/2™.
Declaration function DOSXAMPL( p_inl :integer;
var p_outl :integer;
p_in2 :char ) : integer;
Data Declaration var p_inl,
p_outl :integer;
re :integer;
p_in2 :char;
Invocation re := DOSXAMPL(44,outl,xin2);
IBM C/2™3: This is an example of the interface used with the IBM C/2™.
Declaration int far pascal DOSXAMPL();
Data Declaration int_outl;
int re;
char xin2;
Invocation re= DOSXAMPL(44,(char far*) &outl,xin2);
2 Pascal Compiler/2 is a trademark of
International Business Machines Corporation.