OS2 World Community Forum

OS/2, eCS & ArcaOS - Technical => Programming => Topic started by: Martin Iturbide on June 07, 2016, 04:10:28 pm

Title: The OS/2 API Project at EDM/2
Post by: Martin Iturbide on June 07, 2016, 04:10:28 pm
Hi

I'm going forward to continue helping on the EDM/2 wiki with the "The OS/2 API Project".  I want to try to complete the CPI, PM and any kernel functions for the API documentation.

But I have some doubts that I will like to validate because of my limited knowledge on OS/2 programming.

This is my first doubt.

I have this two functions "Dos32QueryCtryInfo" and "DosQueryCtryInfo" for example. Both are referenced from NLS.DLL and are part of the CPI API.

I would dare to say that they do something similar... "Obtains country-dependent formatting information that resides in the country file. "... but one is compiled on 32bits, but I really do not know about it.

I guess that it makes sense to document each function separately, but I really can not find much information about the "32" functions.

Any suggestions about it?

Regards
Title: Re: The OS/2 API Project at EDM/2
Post by: Dariusz Piatkowski on June 07, 2016, 05:01:23 pm
I think you are right on the money...16-bit vs 32-bit API calls.

For comparison, here is the HPFS386 specific example (direct copy from the Toolkit INF files):

=== START ===
#include <hpfs386.h>
#include <netcons.h>
 
HPFS386GetInfo16(pReserved, pszInfo, sLevel,
           buf, usBuflen, pusBytesAvail);    /* 16 bit */
 
HPFS386GetInfo(pReserved, pszInfo, ulLevel,
           buf, ulBuflen, pusBytesAvail);    /* 32 bit */
=== STOP ===

Here is another example, this one aligned with the naming convention you see:

NetDASDGetInfo or Net32DASDGetInfo

=== START ===
#include <neterr.h>
#include <dasd.h>
 
NetDASDGetInfo(pszServername, pszDirPath, sLevel,
        buf, usBuflen, pusBytesReturned);    /* 16 bit */
 
Net32DASDGetInfo(pszServername, pszDirPath, ulLevel,
        buf, ulBuflen, pulBytesReturned);    /* 32 bit */
=== STOP ===
Title: Re: The OS/2 API Project at EDM/2
Post by: Martin Iturbide on June 09, 2016, 03:17:17 pm
Thanks Dariusz for the reply.

I got an email suggesting me that for the CPI I should follow the "Control Program Guide and Reference" and that the functions listed there are already 32bits, so there is no need to document the ones that I see on DLLs that has the "32" number on it. Notice that I'm just referring to the CPI on this case.

I was told that the developer does not need to consider the APIs that has "32" on its name, except on rare cases.

Regards
Title: Re: The OS/2 API Project at EDM/2
Post by: Dave Yeo on June 09, 2016, 04:20:18 pm
I notice that lxlite -c:exemap NLS.DLL outputs
Code: [Select]
Module Entry Table
 Index ┬ Entry Type ┬ Entry Attributes─────────────────────
 00001 │  Forwarder │ -> DOSCALLS.391(DOSCASEMAP)
 00002 │  Forwarder │ -> DOSCALLS.392(DOSGETCOLLATE)
 00003 │  Forwarder │ -> DOSCALLS.393(DOSGETCTRYINFO)
 00004 │  Forwarder │ -> DOSCALLS.394(DOSGETDBCSEV)
 00005 │  Forwarder │ -> DOSCALLS.395(DosQueryCtryInfo), (DosQueryCtryInfo)
 00006 │  Forwarder │ -> DOSCALLS.396(DosQueryDBCSEnv), (DosQueryDBCSEnv)
 00007 │  Forwarder │ -> DOSCALLS.397(DosMapCase), (DosMapCase)
 00008 ┴  Forwarder ┴ -> DOSCALLS.398(DosQueryCollate), (DosQueryCollate)

No mention of "Dos32QueryCtryInfo"
Title: Re: The OS/2 API Project at EDM/2
Post by: RickCHodgin on June 09, 2016, 06:57:24 pm
I have this two functions "Dos32QueryCtryInfo" and "DosQueryCtryInfo" for example. Both are referenced from NLS.DLL and are part of the CPI API.

This is an almost universal method of extending existing code bases to 32-bits.  In many cases, your compiler can then use a #define statement to include a source file that references the DosQueryCtryInfo() function by name, but has it internally map to the 32-bit version without the source code having to be changed.  And, when you explicitly want to use the 32-bit version, you can call it by name.

Another common one you may see is to use ASCII-based versions, along with UNICODE or Wide-code formats, such as someFunctionA() and someFunctionW(), whereas the actual name is only someFunction() with the extra character portion being tagged on for ease of direct use, but typically not needed.

Best regards,
Rick C. Hodgin
Title: Re: The OS/2 API Project at EDM/2
Post by: Martin Iturbide on June 20, 2016, 05:05:34 pm
Hi

I'm advancing a little bit on the CPI documentation of the API project.  I was suggested to focus on the functions that are part of the latest CPI documentation (CP1.INF (http://cyberkinetica.homeunix.net/os2tk45/cp1/)).

But I'm noticing also that there are some functions from CPI that are referred as "Legacy" and on the latest toolkit version this functions are listed on "PRCP.INF (http://cyberkinetica.homeunix.net/os2tk45/prcp/)"

My questions are: What does it means for this functions to be Legacy? Does it means that developers should try not to use or avoid this functions, even if they keep working? Does it means that there are newer functions that should replace it's functionality?

I haven't finished the CPI API yet, but my general idea (open for discussion) for the legacy functions will be to stack/move it on the same page (http://www.edm2.com/index.php/OS2_API:CPI), but to a lower part before "External References" and make like a new "block" called Legacy.

For the moment (temporary) I had marked as "* Legacy" the functions that are not on CP1.INF and are only on PRCP.INF (Legacy).

Regards
Title: Re: The OS/2 API Project at EDM/2
Post by: RickCHodgin on June 20, 2016, 06:09:35 pm
But I'm noticing also that there are some functions from CPI that are referred as "Legacy" and on the latest toolkit version this functions are listed on "PRCP.INF (http://cyberkinetica.homeunix.net/os2tk45/prcp/)"

My questions are: What does it means for this functions to be Legacy? Does it means that developers should try not to use or avoid this functions, even if they keep working? Does it means that there are newer functions that should replace it's functionality?

A legacy function is something that was used at one point, continues to work correctly, but has since been supplanted by another function.  An example may be a fictional "outputToScreen()" function.  It may have features to allow an x,y coordinate, but no color selection.  So, a new fictional function could be created called "formatToScreen()" which adds both a color and font selection, and is then the preferred function.  The original outputToScreen() function still works, and won't go away (because old software depends on it).  But in moving forward, it's been replaced by the newer function that will receive ongoing maintenance, enhancements, and reflects more accurately the movement of the project / feature.

The designation "legacy" is there to tell developers that there may be something else they want to consider in their design.  But, that doesn't mean it can't be used.  It requires some knowledge of the reasons why you'd need to use it, or not use it.  If, for example, you were writing some code that should compile on versions 2.x, and 3.x of a product, then you may want to use the legacy version even in 3.x because 2.x doesn't have the newer feature, and then you can maintain the smaller single-function code base.

Legacy System on Wikipedia (https://en.wikipedia.org/wiki/Legacy_system)

Quote
I haven't finished the CPI API yet, but my general idea (open for discussion) for the legacy functions will be to stack/move it on the same page (http://www.edm2.com/index.php/OS2_API:CPI), but to a lower part before "External References" and make like a new "block" called Legacy.

For the moment (temporary) I had marked as "* Legacy" the functions that are not on CP1.INF and are only on PRCP.INF (Legacy).

Regards

Best regards,
Rick C. Hodgin
Title: Re: The OS/2 API Project at EDM/2
Post by: Martin Iturbide on June 21, 2016, 02:48:52 pm
Thanks Rick.

I think we may agreed on what we understand as legacy.

I will organize the Legacy functions in other block at the same CPI API (http://www.edm2.com/index.php/OS2_API:CPI) page.

I have a doubt about the EMX project, it seems that it has some functions with the same name of the CPI legacy functions. I also need to check more on that.

I'm also having some doubts with the functions that I marked as " * Can not be found on CP1 or PRCP ". I will try to find more documentation about those and try to identify  if they belong to older version of the CPI.

Any tips are welcome.

Regards
Title: Re: The OS/2 API Project at EDM/2
Post by: RickCHodgin on June 22, 2016, 01:14:51 am
Thanks Rick.

I think we may agreed on what we understand as legacy.

Yes. :-)

Quote
I will organize the Legacy functions in other block at the same CPI API (http://www.edm2.com/index.php/OS2_API:CPI) page.

I have a doubt about the EMX project, it seems that it has some functions with the same name of the CPI legacy functions. I also need to check more on that.

I'm also having some doubts with the functions that I marked as " * Can not be found on CP1 or PRCP ". I will try to find more documentation about those and try to identify  if they belong to older version of the CPI.

Any tips are welcome.

Regards

It is possible that the same named functions exist and are actually separate.  In some types of programming you call things by using a name only.  But in other types of programming, you can call something by name within a scope, allowing the name to be used more than once, but only once within a scope.  That scope can be something called a namespace in C/C++, or (if they are members exposed to a class, struct, or interface) the scope can be the definition of that class, struct, or interface.  In addition, in C++ there is a feature allowed called overloading.  It allows a definition of a particular name to not vary by the name only, but by the associated parameters.

For example:
Code: [Select]
int add(int a);          // One input
int add(int a, int b);   // Two inputs

// Adds 1 to the value a
int add(int a) {
    return(a + 1);
}

// Adds a and b
int add(int a, int b) {
    return(a + b);
}

In this case, the add() name is used correctly more than one place in the same program, but it varies by its parameters.  The first add only has one parameter, and the second has two.  And many such variations are both possible and very common.

It would take some looking into the meaning behind the names to see if they actually are different or not, what their scope is, and why they exist.

Best regards,
Rick C. Hodgin
Title: Re: The OS/2 API Project at EDM/2
Post by: Wim Brul on June 22, 2016, 06:48:44 pm
Hi Martin,

When I look into \TOOLKIT\OS2TK45\H\BSESUB.H then I see that e.g. VioScrollDn is in reality supported by VIO16SCROLLDN and that the argument list described in cp1.inf is in fact incorrect since the argument list described in prcp.inf applies. I checked several other Kbd, Mou and Vio functions and these all appear to be supported the same way i.e. their argument list in cp1.inf is incorrect. It seems to me that all Kbd, Mou and Vio functions must be categorized as 16 bit legacy.

Regards, Wim.
Title: Re: The OS/2 API Project at EDM/2
Post by: Martin Iturbide on June 22, 2016, 10:06:15 pm
Hi Wim.

I'm sorry if I'm slow on this subject and if it is necessary to repeat something to me. I'm not sure if I'm asking the right thing.

What about "VioScrollDown"?  From what I understand "VioScrollDown" is the one that should be used and "VioScrollDn" is legacy. I guess they both do a similar thing. So it will mean (in my limited knowledge) that somebody doing some new development with CPI should avoid using "VioScrollDn" and use "VioScrollDow" instead. Am I right?

On the latest cp1.inf (http://cyberkinetica.homeunix.net/os2tk45/cp1/) I can only find "VioScrollDown" and not "VioScrollDn". I can only find "VioScrollDn" as legacy on prcp.inf (http://cyberkinetica.homeunix.net/os2tk45/prcp/).

For the moment I ignored the functions with "16" on it because someone suggest me (http://www.edm2.com/index.php/Talk:OS2_API:CPI) that developers should use the function without it.  Like on  "Dos32QueryCtryInfo" and "DosQueryCtryInfo" the developer should use (normally) "DosQueryCtryInfo" and for some exception sometimes they might call the 16 one. This is what I understood in short and in my limited knowledge of programming.

But I'm always open for other suggestions. I think that it is important to document everything, and if something that is being documented is wrong and/or old, suggest on that same documentation what should be used instead.

Thanks for helping me out to organize this.

Regards



Title: Re: The OS/2 API Project at EDM/2
Post by: Wim Brul on June 23, 2016, 12:28:25 am
Quote
Hi Wim. I'm sorry if I'm slow on this subject and if it is necessary to repeat something to me. I'm not sure if I'm asking the right thing.

Well, Martin, I am not fast either and it is hard to understand when the official ibm documentation is not in line with the toolkit header and library files.

Quote
What about "VioScrollDown"?  From what I understand "VioScrollDown" is the one that should be used and "VioScrollDn" is legacy. I guess they both do a similar thing. So it will mean (in my limited knowledge) that somebody doing some new development with CPI should avoid using "VioScrollDn" and use "VioScrollDow" instead. Am I right?

Although VioScrollDown appears in cp1.inf it is not present in the header and library files. The developer cannot use it. The developer may only use VioScrollDn since that is the one that is present in the header and library files. I am not sure whether or not the term "legacy" applies. One could argue that a contemporary programmer would produce Presentation Manager type programs only. In that case It would be regarded as "legacy".

Quote
On the latest cp1.inf I can only find "VioScrollDown" and not "VioScrollDn". I can only find "VioScrollDn" as legacy on prcp.inf.

Me too. Apparently 32 bit versions of the 16 bit legacy functions have been documented. Unfortunately these are not supported by the header and library files. Only the 16 bit legacy functions are in there. Therefore these are the only ones available to an application programmer.

Quote
For the moment I ignored the functions with "16" on it because someone suggest me that developers should use the function without it.  Like on "Dos32QueryCtryInfo" and "DosQueryCtryInfo" the developer should use (normally) "DosQueryCtryInfo" and for some exception sometimes they might call the 16 one. This is what I understood in short and in my limited knowledge of programming.

Right you are. You understand well. I only referred to VioScrollDn and Vio16ScrollDn to prove that in fact VioScrollDn is a 16 bit function.

Quote
But I'm always open for other suggestions. I think that it is important to document everything, and if something that is being documented is wrong and/or old, suggest on that same documentation what should be used instead.

Yes. Let's keep on trying when time permits.

Title: Re: The OS/2 API Project at EDM/2
Post by: Dave Yeo on June 23, 2016, 01:54:10 am
I think that IBM had 32 bit cmd.exe in the pipeline and released in beta (alpha?) state on one of those CDs for developers and then retreated, probably as development/funding ended.  Unluckily it appears that the latest toolkit was ahead of the latest release.
As Wim noted, the headers (and libraries) are the most accurate documentation.
Title: Re: The OS/2 API Project at EDM/2
Post by: Martin Iturbide on June 23, 2016, 05:40:08 pm
Hi.

I understand the issue better now.

I want to check the headers of the OS/2 Toolkit 4.5 and see if I can understand those and try to make a quick list (on other page of the wiki) on which functions may be available on the CP1 documentation, but missing on the headers.

Since I see that all the headers on toolkit are on /H directory and I only want to focus on the CPI components for the moment, which are the .H files that I should be looking at? Does this question makes sense ?

Regards
Title: Re: The OS/2 API Project at EDM/2
Post by: Martin Iturbide on June 23, 2016, 06:03:23 pm
Hi

I also did a quick and dirty search of "VioScrollDown" with Dataseek on my hard drive. (Check attachment)
It was only referenced on CP1.INF and RXTT36.INF.

Does that function really exists? or just in documentation and was never implemented?
If so, I think I need to mark it on the Wiki that it was never implemented and does not work.

Regards
Title: Re: The OS/2 API Project at EDM/2
Post by: Dave Yeo on June 24, 2016, 02:20:55 am
It might exist in a DLL and only referenced by ordinal, and without knowing the ordinal. There are undocumented functions hiding behind ordinal numbers, eg a comment in Cairo/src/cairo-os2-private.h says
Quote
/**
 * Unpublished API:
 *   GpiEnableYInversion = PMGPI.723
 *   GpiQueryYInversion = PMGPI.726
 **/
It also exists on the DevCon3 CD according to this article, http://www.verycomputer.com/3_93ea71e0279eddf3_1.htm (http://www.verycomputer.com/3_93ea71e0279eddf3_1.htm) and probably in the PPC version of OS/2
Title: Re: The OS/2 API Project at EDM/2
Post by: RickCHodgin on June 24, 2016, 05:56:15 am
Quote
On the latest cp1.inf I can only find "VioScrollDown" and not "VioScrollDn". I can only find "VioScrollDn" as legacy on prcp.inf.

Me too. Apparently 32 bit versions of the 16 bit legacy functions have been documented. Unfortunately these are not supported by the header and library files. Only the 16 bit legacy functions are in there. Therefore these are the only ones available to an application programmer.

You may be able to still access those functions if you know their name and which dll they reside in.  You can use a function equivalent of LoadLibrary() and GetProcAddress(), which will open the dll and locate the entry point within the dll to access the function.  If the 32-bit equivalents / wrappers to the 16-bit versions exist, they may be exposed only in that way.

It is possible, for example, that they do exist internally, but are not exposed through the normal header files because the IBM authors did not want people to use them, but only those people who really really had a need and therefore knew what they were doing by accessing the functions directly.

Here is some code in my Visual FreePro project whereby I access functions explicitly manually within a DLL by name:

See lines 226 and 230 (https://github.com/RickCHodgin/libsf/blob/master/source/vfrp/core/oss/oss_plugins.cpp)
Note:  OSS stands for operating system specific.

It's also possible they do not exist.  A enumeration of the functions actually contained in each DLL would be desirable to then compare against the names exposed through documented source code APIs.

Best regards,
Rick C. Hodgin
Title: Re: The OS/2 API Project at EDM/2
Post by: Dave Yeo on June 24, 2016, 06:53:57 am
The problem is that most OS/2 DLLs export functions by ordinal rather then by name, so you need to know the ordinal number of a function to directly call it. eg the Doscalls entry points (the loader does some magic here and can resolve by name sometimes and also will fallback to doscall1 if not loaded from doscalls or the version in doscalls is ring 0 code and a user needs ring3 as I understand it) http://home.clara.net/orac/os2/doscalls.htm (http://home.clara.net/orac/os2/doscalls.htm), who knows if anything is between 1117 and 9004 or what 9009, 9012-9018 and 9019+ reference.
Title: Re: The OS/2 API Project at EDM/2
Post by: RickCHodgin on June 24, 2016, 07:26:30 am
The problem is that most OS/2 DLLs export functions by ordinal rather then by name, so you need to know the ordinal number of a function to directly call it. eg the Doscalls entry points (the loader does some magic here and can resolve by name sometimes and also will fallback to doscall1 if not loaded from doscalls or the version in doscalls is ring 0 code and a user needs ring3 as I understand it) http://home.clara.net/orac/os2/doscalls.htm (http://home.clara.net/orac/os2/doscalls.htm), who knows if anything is between 1117 and 9004 or what 9009, 9012-9018 and 9019+ reference.

Has anyone tried requesting ordinals between 1117 and 9004 to see if it returns something valid?  If so, we could disassemble the code within and see if it's a wrapper to any other function.

Here's a simple disassembler (https://github.com/RickCHodgin/libsf/tree/master/exodus/tools/debi) I wrote for 32-bit code (no direct 16-bit support without explicit overrides).  It compiles under Windows using Visual Studio (and will probably still compile under GCC as I originally wrote it in Eran Ifrah's CodeLite using the GCC+GDB toolchain in Linux, though it might need a few tweaks).

Best regards,
Rick C. Hodgin
Title: Re: The OS/2 API Project at EDM/2
Post by: Dave Yeo on June 24, 2016, 08:05:58 am
Has anyone tried requesting ordinals between 1117 and 9004 to see if it returns something valid?  If so, we could disassemble the code within and see if it's a wrapper to any other function.

I don't know if anyone has requested the ordinals and requesting from user land might fail anyways if they're ring 0 functions. (some functions come in both ring0 and ring3 versions)
As for disassembling, understand that doscalls is split between the kernel and doscall1.dll though I guess the OS4 guys may well have as they've re-implemented both the kernel and doscall1.dll.

I'm right at the edge of my knowledge of this stuff and perhaps beyond.
Title: Re: The OS/2 API Project at EDM/2
Post by: Wim Brul on June 24, 2016, 11:57:05 am
I want to check the headers of the OS/2 Toolkit 4.5 and see if I can understand those and try to make a quick list (on other page of the wiki) on which functions may be available on the CP1 documentation, but missing on the headers.

Since I see that all the headers on toolkit are on /H directory and I only want to focus on the CPI components for the moment, which are the .H files that I should be looking at? Does this question makes sense ?

The main include is OS2.H which leads you to BSE.H which in turn leads you to BSEDOS.H (for Dos functions) and BSESUB.H (for Kbd, Mou and Vio functions).
Title: Re: The OS/2 API Project at EDM/2
Post by: Martin Iturbide on June 24, 2016, 04:33:01 pm
Thanks Wim. I will be checking those headers from the OS2TK45.
I'm going to mark as "* Not Implemented" the ones that I can found.

For the moment I got:
- VioScrollDown
- VioScrollLeft
- VioScrollRight

Anybody that know any other functions, please post it so I can also validate it and mark those.

As for disassembling, understand that doscalls is split between the kernel and doscall1.dll....

This is also interesting. For what I know DOSCALLS.DLL is from older OS/2 version and the latest ones has DOSCALL1.DLL. But I never was able to understand or list which functions are now on the kernel, I guess that is the OS2KRNL file. I also  want to update the kernel part the OS2 API project, but I want to focus on CPI first. Maybe I will ask this later.

Regards

Title: Re: The OS/2 API Project at EDM/2
Post by: Wim Brul on June 24, 2016, 05:47:26 pm
Hi Martin,

When I look into \TOOLKIT\OS2TK45\H\BSESUB.H then I see that e.g. VioScrollUp is in reality supported by VIO16SCROLLUP and that the argument list described in cp1.inf is in fact incorrect since the argument list described in prcp.inf applies. I checked several other Kbd, Mou and Vio functions and these all appear to be supported the same way i.e. their argument list in cp1.inf is incorrect. Consequently all Kbd, Mou and Vio functions need to be marked as ** Not implemented *.

Regards

Title: Re: The OS/2 API Project at EDM/2
Post by: Martin Iturbide on June 24, 2016, 07:01:39 pm
Hi.

So let me get the issues.

1) There are some functions that are listed on CP1 but not implemented on the headers of OS2TK45.

I searched the OS2TK45 *.h files and found out this ones that does not seems to have a definition on the headers:

Code: [Select]
VioScrollDown  - not found
VioScrollLeft  - not found
VioScrollRight   - not found
VioGetOrigin  - not found
VioSetOrigin   - not found
KbdGetConsole  - not found
KbdGetLayout  - not found
KbdGetLayoutUni  - not found
KbdSetLayout  - not found
DosSuppressPopUps  -  Looks strange. incomplete? No APIRET no Ordinal
DosDumpProcess  -  Looks strange. incomplete? No APIRET no Ordinal
DosForceSystemDump  - not found

Can someone validate these since my method is not fail-proof ?

In this case I plan to put some warning inside the functions. Something like "Warning: This function has not been found or implemented on the headers of OS2TK45".  Is it ok? any better wording?

Regards
Title: Re: The OS/2 API Project at EDM/2
Post by: Martin Iturbide on June 24, 2016, 07:13:18 pm
Hi. 

I didn't liked the other issue.

Issue 2) The second issue is that there functions on CP1.INF that are also on the legacy (prcp.INF), but the CP1 function is not specified correctly. Which it also means that those CP1 functions have not been implemented, and only the legacy documentation should apply. right?

For example:

VioScrollUp from CP1.INF says:

Code: [Select]
ULONG     TopRow;     /*  Top row to be scrolled. */
ULONG     LeftCol;    /*  Left column to be scrolled. */
ULONG     BotRow;     /*  Bottom row to be scrolled. */
ULONG     RightCol;   /*  Right column to be scrolled. */
ULONG     Lines;      /*  Number of lines. */
PBYTE     Cell;       /*  Cell to be written. */
HVIO      VioHandle;  /*  VIO presentation-space handle. */
APIRET    rc;         /*  Return code. */

rc = VioScrollUp(TopRow, LeftCol, BotRow,
       RightCol, Lines, Cell, VioHandle);

VioScrollUp from prcp.inf (legacy) says:

Quote
VioScrollUp   (TopRow, LeftCol, BotRow, RightCol, Lines, Cell, VioHandle)

TopRow (USHORT) - input
LeftCol (USHORT) - input
BotRow (USHORT) - input
RightCol (USHORT) - input
Lines (USHORT) - input
Cell (PBYTE) - input
VioHandle (HVIO) - input

OS2TK45 has:

bseord.h:
Code: [Select]
/* VIOCALLS */
#define ORD_VIOSCROLLUP          7


bsesub.h
Code: [Select]
#define VioScrollUp             VIO16SCROLLUP
...
#define VR_VIOSCROLLUP             0x00040000L
...   
   APIRET16 APIENTRY16  VioScrollUp (USHORT usTopRow,
                                     USHORT usLeftCol,
                                     USHORT usBotRow,
                                     USHORT usRightCol,
                                     USHORT cbLines,
                                     PBYTE pCell,
                                     HVIO hvio);


If you call VIOSCROLLUP but sending ULONG parameters (like CP1 says) will it not work?

Is there a way to confirm that CP1's VIOSCROLLUP (the new one) does not exists at all? Or what I posted is enough evidence? I'm not sure about it.

If it does not work, that would mean to me that I also need to document the legacy functions, and also put some warning on it that even that there is a "non-legacy function" you still need to use the legacy one because the newer one does not work. Does it makes sense?

I will need to think about it which will be a good way to document this on the CPI API Project.

Regards
Title: Re: The OS/2 API Project at EDM/2
Post by: RickCHodgin on June 24, 2016, 07:23:09 pm
Hi. 

I didn't liked the other issue.

Issue 2) The second issue is that there functions on CP1.INF that are also on the legacy (prcp.INF), but the CP1 function is not specified correctly. Which it also means that those CP1 functions have not been implemented, and only the legacy documentation should apply. right?

I think the difference you're seeing is 16-bit and 32-bit.  The 16-bit functions use USHORT, which is a 2-byte (16-bit) quantity on x86 CPUs, whereas the ULONG is a 4-byte (32-bit) quantity.  The "U" means unsigned, and the SHORT is 16-bit, with LONG being 32-bit.

Variable size info (https://en.wikipedia.org/wiki/Integer_(computer_science)#Common_integral_data_types).  Things are typically signed, but you must then prefix with "u" to make it unsigned, so "short" becomes "ushort", and "long" becomes "ulong", etc.

You're also seeing an evolution there over time of a preferred method of data exchange between functions.  The newer ULONG function includes an extra parameter which is the return value, rather than passing it externally.  This allows the destination of the return value to be specified as an input parameter, rather than relying on the calling convention.

Quote
For example:

VioScrollUp from CP1.INF says:

Code: [Select]
ULONG     TopRow;     /*  Top row to be scrolled. */
ULONG     LeftCol;    /*  Left column to be scrolled. */
ULONG     BotRow;     /*  Bottom row to be scrolled. */
ULONG     RightCol;   /*  Right column to be scrolled. */
ULONG     Lines;      /*  Number of lines. */
PBYTE     Cell;       /*  Cell to be written. */
HVIO      VioHandle;  /*  VIO presentation-space handle. */
APIRET    rc;         /*  Return code. */

rc = VioScrollUp(TopRow, LeftCol, BotRow,
       RightCol, Lines, Cell, VioHandle);

I don't think this is correct.  I think it should be like this with the return value passed in as a parameter:

Code: [Select]
VioScrollUp(TopRow, LeftCol, BotRow, RightCol, Lines, Cell, VioHandle, &rc);

In the alternative, it should be like this:
Code: [Select]
Input:
ULONG     TopRow;     /*  Top row to be scrolled. */
ULONG     LeftCol;    /*  Left column to be scrolled. */
ULONG     BotRow;     /*  Bottom row to be scrolled. */
ULONG     RightCol;   /*  Right column to be scrolled. */
ULONG     Lines;      /*  Number of lines. */
PBYTE     Cell;       /*  Cell to be written. */
HVIO      VioHandle;  /*  VIO presentation-space handle. */
Output:
APIRET    rc;         /*  Return code. */

rc = VioScrollUp(TopRow, LeftCol, BotRow,
       RightCol, Lines, Cell, VioHandle);

Quote
VioScrollUp from prcp.inf (legacy) says:

Quote
VioScrollUp   (TopRow, LeftCol, BotRow, RightCol, Lines, Cell, VioHandle)

TopRow (USHORT) - input
LeftCol (USHORT) - input
BotRow (USHORT) - input
RightCol (USHORT) - input
Lines (USHORT) - input
Cell (PBYTE) - input
VioHandle (HVIO) - input

OS2TK45 has:

bseord.h:
Code: [Select]
/* VIOCALLS */
#define ORD_VIOSCROLLUP          7


bsesub.h
Code: [Select]
#define VioScrollUp             VIO16SCROLLUP
...
#define VR_VIOSCROLLUP             0x00040000L
...   
   APIRET16 APIENTRY16  VioScrollUp (USHORT usTopRow,
                                     USHORT usLeftCol,
                                     USHORT usBotRow,
                                     USHORT usRightCol,
                                     USHORT cbLines,
                                     PBYTE pCell,
                                     HVIO hvio);

Is there a way to confirm that CP1's VIOSCROLLUP (the new one) does not exists at all? Or what I posted is enough evidence? I'm not sure about it.

Is there some source code that can be compiled and examined to see what it links to internally?  You'll be able to tell by the calling convention in the assembly output, if it pushes 16-bit or 32-bit quantities.

Quote
That means to me that I also need to document the legacy functions, and also put some warning on it that even that there is a "non-legacy function" you still need to use the legacy one because the newer one does not work. Does it makes sense?

I will need to think about it which will be a good way to document this on the CPI API Project.

Regards

Once I get my C/C++ compiler parser far enough along, maybe we can automate some of this and regenerate from the ground-up based on a system-wide examination of the DLLs and the header files and libraries, the entire system API.  By parsing it into this type of tool, we can then directly wield it and generate documentation, along with wrappers for other purposes.

I won't have that completed until later this year (Lord willing).  It's a fairly substantial task, and it's not slated to begin until sometime around September.

Best regards,
Rick C. Hodgin
Title: Re: The OS/2 API Project at EDM/2
Post by: Martin Iturbide on June 26, 2016, 07:19:08 pm
Hi.

For the moment I will organize CPI API like I set it up on the page. (http://www.edm2.com/index.php/OS2_API:CPI)

The latest documentation (CP1 and Addendum) is going to be on the top. 
The Legacy (PRCP) is going to be after that on the next block. On the legacy functions I'm going to name the pages of the functions:  "OS2 API:CPI:LEGACY:xxxxxxx" so they can not be confused with the CP1 ones. 

Regards
Title: Re: The OS/2 API Project at EDM/2
Post by: Wim Brul on July 03, 2016, 12:07:32 pm
Quote
Issue 2) The second issue is that there functions on CP1.INF that are also on the legacy (prcp.INF), but the CP1 function is not specified correctly. Which it also means that those CP1 functions have not been implemented, and only the legacy documentation should apply. right?
Yes. CP1.INF contains tentative documentation of 32 bit functions intended to replace those16 bit legacy functions.
Quote
If you call VIOSCROLLUP but sending ULONG parameters (like CP1 says) will it not work?
That will not work.
Quote
Is there a way to confirm that CP1's VIOSCROLLUP (the new one) does not exists at all? Or what I posted is enough evidence? I'm not sure about it.
For me that is enough evidence. I also inspected os2386.lib and those tentative functions are absent  whereas those legacy functions are present.
Quote
If it does not work, that would mean to me that I also need to document the legacy functions, and also put some warning on it that even that there is a "non-legacy function" you still need to use the legacy one because the newer one does not work. Does it makes sense?
Only the 16 bit legacy functions need to be documented. I would omit that tentative documentation completely because it would only lead to confusion.
Title: Re: The OS/2 API Project at EDM/2
Post by: Martin Iturbide on July 03, 2016, 04:12:34 pm
Thanks for the feedback.

Wim, can you let me know how to inspect the .LIB files?  Any tools? I really do now know anything about those files. How do you see it's internals?

Regards
Title: Re: The OS/2 API Project at EDM/2
Post by: Wim Brul on July 03, 2016, 10:44:22 pm
Wim, can you let me know how to inspect the .LIB files?  Any tools? I really do now know anything about those files. How do you see it's internals?

Hi Martin,

With the IBM Library Manager you can a.o. create a cross-reference listing file from a library file.

A cross-reference listing file contains two lists. The first is an alphabetic listing of all public symbols in the library. The name of the module, the symbol name refers to, comes after that symbol name.

The second list is an alphabetic list of the modules in the library. Under each module name is an alphabetic listing of the public symbols the module refers to.

Code: [Select]
lib.exe os2386.lib,os2386.lst;

You may find lib.exe in the ddk. It is not present in os2tk45. An alternative is the Microsoft Library Manager contained in c7os2.zip on hobbes.

Regards
Title: Re: The OS/2 API Project at EDM/2
Post by: Dave Yeo on July 04, 2016, 12:07:52 am
You can also use emximp, eg
Code: [Select]
G:\os2tk45\lib>emximp -o os2386.imp os2386.libwhich will output a imp file with eg the head of os2386.imp
Quote
;
; os2386.imp (created by emximp)
;
; -------- os2386.lib --------
DOSPTRACE               DOSCALLS  12 ?
DOSISETRELMAXFH         DOSCALLS 108 ?
DOSIDEVIOCTL            DOSCALLS 109 ?
DosForceDelete          DOSCALLS 110 ?
Dos32ForceDelete        DOSCALLS 110 ?
DosKillThread           DOSCALLS 111 ?
Dos32KillThread         DOSCALLS 111 ?
DosQueryRASInfo         DOSCALLS 112 ?
Dos32QueryRASInfo       DOSCALLS 112 ?
DosDumpProcess          DOSCALLS 113 ?
Dos32DumpProcess        DOSCALLS 113 ?
DosSuppressPopUps       DOSCALLS 114 ?
Dos32SuppressPopUps     DOSCALLS 114 ?
...
Title: Re: The OS/2 API Project at EDM/2
Post by: Martin Iturbide on July 04, 2016, 04:06:51 pm
Thanks for the feedback. I also created a little page to don't forget about it on the EDM/2 Wiki (Extracting information from LIB files (http://www.edm2.com/index.php/Extracting_information_from_LIB_files)).

I will continue little by little to complete the CPI API page (http://www.edm2.com/index.php/OS2_API:CPI).

Regards
Title: Re: The OS/2 API Project at EDM/2
Post by: Martin Iturbide on August 09, 2016, 10:14:55 pm
Hi

I keep going little by little to complete the CPI API page (http://www.edm2.com/index.php/OS2_API:CPI).

But I had also changed the structure of the OS/2 API Page on the EDM/2 (http://www.edm2.com/index.php/Category:The_OS/2_API_Project). It is just experimental to see if it works.
I had changed the page in three blocks:
- OS/2 Product APIs - The APIs that came with the OS/2 Warp product
- Third Parties OS/2 Based APIs - APIs that had been created "almost" exclusively for OS/2.
- OS/2 Ported APIs - Which are mostly the APIs that had been ported to OS/2 and have it's documentation somewhere else.

The idea is that the first two blocks will have more detailed documentation of the API, if I ever finish it, while the third block will only have the reference to the website with its API documentation.

Please check it out to see if it is easy to understand or any corrections/suggestion that you may have.

Regards
Title: Re: The OS/2 API Project at EDM/2
Post by: RickCHodgin on August 10, 2016, 03:28:10 pm
Hi

I keep going little by little to complete the CPI API page (http://www.edm2.com/index.php/OS2_API:CPI).

But I had also changed the structure of the OS/2 API Page on the EDM/2 (http://www.edm2.com/index.php/Category:The_OS/2_API_Project). It is just experimental to see if it works.
I had changed the page in three blocks:
- OS/2 Product APIs - The APIs that came with the OS/2 Warp product
- Third Parties OS/2 Based APIs - APIs that had been created "almost" exclusively for OS/2.
- OS/2 Ported APIs - Which are mostly the APIs that had been ported to OS/2 and have it's documentation somewhere else.

The idea is that the first two blocks will have more detailed documentation of the API, if I ever finish it, while the third block will only have the reference to the website with its API documentation.

Please check it out to see if it is easy to understand or any corrections/suggestion that you may have.

I plan to implement all of these once I get my kernel compiling under my own assembler.  I'm going little by little on my assembler presently.  My assembler is a 7-pass assembler, and I'm up to pass-3 and expression parsing for instructions like "mov eax,[esi+ebx+4]".  Pass-3 is the last source code pass, and then it's on to internal calculations for passes X,Y,Z, which are output file generation passes.  You can see the source code here (https://github.com/RickCHodgin/libsf/tree/master/exodus/tools/lsa) on GitHub.

I have all of the file parsing, #include file parsing, and all #define and macro statements working.

See my follow-up reply here (http://www.os2world.com/forum/index.php?topic=983.msg10669#msg10669).

Best regards,
Rick C. Hodgin
Title: Re: The OS/2 API Project at EDM/2
Post by: Martin Iturbide on August 24, 2016, 07:15:43 pm
Hi

Does anybody know something about this file "CPMBC21B.DLL".  It is referred as "ObjectPM Core Library for Borland v21B".
http://www.edm2.com/index.php/CPMBC21B.DLL

I just found it on the Hint Bubble (http://www.edm2.com/index.php/Hint_Bubble) package and I want to see where it comes from. From Borland?

Anybody has some documentation, pointers, ideas about it?


I think I found it, it is part of the ObjectPM (http://www.edm2.com/index.php/ObjectPM) product from Secant Technologies. It would be interesting if someone has the ObjectPM package with full source code (it was used to be sold also with source code) to see if I can ask permission to change its license to open source.

Regards


Regards
Title: Re: The OS/2 API Project at EDM/2
Post by: Martin Iturbide on August 29, 2016, 05:35:54 pm
Hi

I found that article from PC Mag when the OS/2 2.0 API was released.

https://books.google.com.ec/books?id=u7WbsmbttwYC&pg=PT372&lpg=PT372&dq#v=onepage&q&f=false (https://books.google.com.ec/books?id=u7WbsmbttwYC&pg=PT372&lpg=PT372&dq#v=onepage&q&f=false)

It was interesting to see those tables of which functions got renamed and which was eliminated.

Regards
Title: Re: The OS/2 API Project at EDM/2
Post by: Martin Iturbide on August 29, 2016, 05:49:16 pm
Hi

I also can not find much information about "DosQueryFileMode".
A search on OS/2 showed me some references on "OS2TRACE.INF" and "strace.inf" but it only gives me some "Hook ID" on a table.

I can not find it Warp 4.52.

On the PC Mag article (https://books.google.com.ec/books?id=u7WbsmbttwYC&pg=PT372&lpg=PT372&dq#v=onepage&q=DosQueryFileMode&f=false) (of OS/2 2.0 API) say "DosQueryFileMode" replaces ""DosQFileMode".

Should I put is as "Not Implemented" ?

Regards
Title: Re: The OS/2 API Project at EDM/2
Post by: RickCHodgin on August 29, 2016, 08:58:20 pm
Hi

I also can not find much information about "DosQueryFileMode".
A search on OS/2 showed me some references on "OS2TRACE.INF" and "strace.inf" but it only gives me some "Hook ID" on a table.

I can not find it Warp 4.52.

On the PC Mag article (https://books.google.com.ec/books?id=u7WbsmbttwYC&pg=PT372&lpg=PT372&dq#v=onepage&q=DosQueryFileMode&f=false) (of OS/2 2.0 API) say "DosQueryFileMode" replaces ""DosQFileMode".

Should I put is as "Not Implemented" ?

Regards

I found this reference (http://www.verycomputer.com/3_e3024b77eaba57a1_1.htm) from toolkits 2.0 and 2.1, which indicate it no longer existed there.  The responder writes:

"Try DosQueryFileInfo and DosSetFileInfo if you have the file open (ie. you have a handle).  Use DosQueryPathInfo and DosSetPathInfo if the file isn't open or you want to set the attributes for a directory."

So I would say it's either not implemented, exists as something hidden, or was simply dropped as it migrated to new functionality in the other functions.

Best regards,
Rick C. Hodgin
Title: Re: The OS/2 API Project at EDM/2
Post by: Martin Iturbide on August 29, 2016, 11:47:24 pm
Thanks for the pointer Rick.

In general terms, I'm almost done with the Control Program functions page. It may never be perfect, but I think it is decent enough.
Check the page at:
http://www.edm2.com/index.php/OS2_API:CPI (http://www.edm2.com/index.php/OS2_API:CPI)

I added some icons with a "warning logo" on some functions to represent that "it may not be implemented"
On the legacy functions, in some functions, I had added a "question mark icon" which means that the information need to be complete.

So....
1) If anybody has more information about the ones with "Question Mark", let me know, post it here, etc.
2) If there is any other non-legacy function that deserves the "warning icon" please let me know too.
3) Let me know any other things I may be missing about the CPI functions.


Regards

Title: Re: The OS/2 API Project at EDM/2
Post by: Dave Yeo on August 30, 2016, 01:05:42 am
Are you aware of this, https://winworldpc.com/product/ibm-developers-toolkit (https://winworldpc.com/product/ibm-developers-toolkit)? Should help with the 16bit API.
Title: Re: The OS/2 API Project at EDM/2
Post by: Martin Iturbide on August 30, 2016, 02:39:24 pm
Thanks Dave?

I want to check if it has some documentation. How do I unpack those files on a newer OS/2? Is there a batch way to do it instead of going with unpack file by file?
Regards
Title: Re: The OS/2 API Project at EDM/2
Post by: Martin Iturbide on September 25, 2016, 06:00:58 pm
Hi

I'm trying to find more information for the EDM/2 wiki about this legacy functions:

DOSPMSEMWAIT
DOSPMMUXSEMWAIT
DosSGQueryTopmost
KbdInit
KbdLoadInstance
KbdSwitchFgnd
KbdShellInit
KbdFree
KbdSetHWId

VioFree
Avs_Prtsc
VioSrfUnblock
VioSrfBlock
ioSave
VioHetInit
VioSswSwitch
Avs_PrtscToggle
VioInit
VioRestore
VioShellInit

VioGetPSAddress
VioQueryConsole
XVioSetCAState
XVioCheckCharType
XVioDestroyCA
XVioCreateCA
XVioGetCAState

DosSMRealPrtSc

Also there are some other Legacy functions that I needs more information and are listed with "question mark" on this page:
http://www.edm2.com/index.php/OS2_API:CPI#Legacy_Functions (http://www.edm2.com/index.php/OS2_API:CPI#Legacy_Functions)

Regards