Manual de Programación en OS/2 - ACCESO AL API DE OS/2

OS/2 es un S.O. pensado para poder ser programado tanto desde lenguajes de alto nivel (C, Pascal, Basic) como de bajo nivel (Assembler). Para facilitar la llamada a funciones desde los primeros, todos los parámetros se pasan por medio de la pila de máquina, y solo devuelve un código de error en el registro AX. Para facilitar las llamadas en el segundo, éstas no se implementan como saltos a supervisor, sino como FARCALLs, de modo que para un programador de código máquina no habrá diferencia entre ejecutar una llamada a una función del sistema o llamar a una función propia.

Hay tres tipos de datos que se pueden pasar a una función de OS/2: un byte (8 bits), una doble palabra (32 bits) o un puntero (32 bits), y retorna un valor de 16 bits en el acumulador (AX). Sin embargo, para facilitar la lectura de los programas, en la libreria se han definido diversos tipos que ayudan en la programación, como por ejemplo, todas las estructuras de datos necesarias en muchos de los programas. Estos tipos están definidos EN MAYUSCULAS, y serán usados en la definición de cada llamada en este curso. En el caso de llamadas al API de 32 bits (llamadas DOS y WIN), no hay peligro en cambiar el tipo predefinido por un INT, CHAR... pero en las llamadas al API de 16 bits puede ser problematico, pues se puede devolver un entero de 16 bits, de 32, etc. En estos casos (que, por fortuna, son muy pocos) conviene utilizar los tipos definidos en la libreria, escribiendolos, por tanto, en MAYUSCULAS.

Todas las definiciones de las funciones y estructuras están definidas en el fichero OS2.H. Sin embargo, no es suficiente con añadir un #include <os2.h> al principio del programa, sino que debemos definir primero qué partes queremos que se incluyan, mediante una serie de sentencias #define. Existen varias importantes, pero en general, suele bastar con añadir un #define "INCL_BASE", la cual se encarga de definir automáticamente INCL_DOS (llamadas DOSxxx) INCL_DOSERRORS (códigos de error) e INCL_SUB (llamadas a subsistemas), la cual simplemente define INCL_KBD, INCL_VIO e INCL_MOU. Con ésto es suficiente para realizar casi cualquier programa de OS/2.

Dado que solo hay un código que OS/2 devuelve, y éste está reservado para el código de error, cuando OS/2 tiene que entregar algún dato, necesita que le demos como parámetro un puntero a una zona de memoria donde pueda dejarlo. Trabajando con C, basta con que le demos un puntero a una variable del tipo adecuado. Así, si OS/2 tiene que devolvernos, por ejemplo, el número de bytes que se han leido de un fichero, debemos darle entre los parámetros de la función un puntero a una variable donde podrá almacenar ese resultado.

En la descripción de las funciones, cuando una variable es de tipo puntero lleva antepuesta una p, además de estar indicado en la descripción de los parámetros. Por supuesto, es posible definir la variable como tal en vez de como un puntero, y usar el símbolo & al pasar el parámetro a la función.