Author Topic: The OS/2 API Project at EDM/2  (Read 28585 times)

Martin Iturbide

  • OS2World NewsMaster
  • Global Moderator
  • Hero Member
  • *****
  • Posts: 4713
  • Karma: +41/-1
  • Your Friend Wil Declares...
    • View Profile
    • Martin's Personal Blog
The OS/2 API Project at EDM/2
« 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
Martin Iturbide
OS2World NewsMaster
... just share the dream.

Dariusz Piatkowski

  • Hero Member
  • *****
  • Posts: 1317
  • Karma: +26/-0
    • View Profile
Re: The OS/2 API Project at EDM/2
« Reply #1 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 ===

Martin Iturbide

  • OS2World NewsMaster
  • Global Moderator
  • Hero Member
  • *****
  • Posts: 4713
  • Karma: +41/-1
  • Your Friend Wil Declares...
    • View Profile
    • Martin's Personal Blog
Re: The OS/2 API Project at EDM/2
« Reply #2 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
Martin Iturbide
OS2World NewsMaster
... just share the dream.

Dave Yeo

  • Hero Member
  • *****
  • Posts: 4787
  • Karma: +99/-1
    • View Profile
Re: The OS/2 API Project at EDM/2
« Reply #3 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"

RickCHodgin

  • Guest
Re: The OS/2 API Project at EDM/2
« Reply #4 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

Martin Iturbide

  • OS2World NewsMaster
  • Global Moderator
  • Hero Member
  • *****
  • Posts: 4713
  • Karma: +41/-1
  • Your Friend Wil Declares...
    • View Profile
    • Martin's Personal Blog
Re: The OS/2 API Project at EDM/2
« Reply #5 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).

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"

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, 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
Martin Iturbide
OS2World NewsMaster
... just share the dream.

RickCHodgin

  • Guest
Re: The OS/2 API Project at EDM/2
« Reply #6 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"

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

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, 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
« Last Edit: June 20, 2016, 11:48:54 pm by Rick C. Hodgin »

Martin Iturbide

  • OS2World NewsMaster
  • Global Moderator
  • Hero Member
  • *****
  • Posts: 4713
  • Karma: +41/-1
  • Your Friend Wil Declares...
    • View Profile
    • Martin's Personal Blog
Re: The OS/2 API Project at EDM/2
« Reply #7 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 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
Martin Iturbide
OS2World NewsMaster
... just share the dream.

RickCHodgin

  • Guest
Re: The OS/2 API Project at EDM/2
« Reply #8 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 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
« Last Edit: June 22, 2016, 06:47:30 pm by Rick C. Hodgin »

Wim Brul

  • Sr. Member
  • ****
  • Posts: 295
  • Karma: +25/-0
    • View Profile
    • Wim's home page
Re: The OS/2 API Project at EDM/2
« Reply #9 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.

Martin Iturbide

  • OS2World NewsMaster
  • Global Moderator
  • Hero Member
  • *****
  • Posts: 4713
  • Karma: +41/-1
  • Your Friend Wil Declares...
    • View Profile
    • Martin's Personal Blog
Re: The OS/2 API Project at EDM/2
« Reply #10 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 I can only find "VioScrollDown" and not "VioScrollDn". I can only find "VioScrollDn" as legacy on prcp.inf.

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.

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



Martin Iturbide
OS2World NewsMaster
... just share the dream.

Wim Brul

  • Sr. Member
  • ****
  • Posts: 295
  • Karma: +25/-0
    • View Profile
    • Wim's home page
Re: The OS/2 API Project at EDM/2
« Reply #11 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.


Dave Yeo

  • Hero Member
  • *****
  • Posts: 4787
  • Karma: +99/-1
    • View Profile
Re: The OS/2 API Project at EDM/2
« Reply #12 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.

Martin Iturbide

  • OS2World NewsMaster
  • Global Moderator
  • Hero Member
  • *****
  • Posts: 4713
  • Karma: +41/-1
  • Your Friend Wil Declares...
    • View Profile
    • Martin's Personal Blog
Re: The OS/2 API Project at EDM/2
« Reply #13 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
Martin Iturbide
OS2World NewsMaster
... just share the dream.

Martin Iturbide

  • OS2World NewsMaster
  • Global Moderator
  • Hero Member
  • *****
  • Posts: 4713
  • Karma: +41/-1
  • Your Friend Wil Declares...
    • View Profile
    • Martin's Personal Blog
Re: The OS/2 API Project at EDM/2
« Reply #14 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
Martin Iturbide
OS2World NewsMaster
... just share the dream.