Talk:Control Program Functions

Andreas Changes
Maybe we should make a fork of this page. To have one page with the Function and quick description (like: DosClose - Closes a file handle ) and other page just listing the functions like it was originally. Martini (talk) 04:24, 30 August 2017 (CEST)

I forked this page to Control Program Functions List while Andreas finish the idea of this page 14:51, 14 September 2017 (CEST)

Issues 1 - the 16 or 32
17:04, 7 June 2016 (CEST) I'm still not sure to included this on the CPI page. Not sure if this is legacy that was depreciated.

National Language Support
This are from the NLS.DLL component
 * Dos32QueryCtryInfo
 * Dos32QueryDBCSEnv
 * Dos32MapCase
 * Dos32QueryCollate

Memory Suballocation

 * Dos32SubSetMem
 * Dos32SubAllocMem
 * Dos32SubFreeMem
 * Dos32SubUnSetMem

Martini (talk) 22:31, 8 June 2016 (CEST)I got this suggestion  Hi, Just a suggestion. When documenting APIs, I recommend you follow the lead of the IBM "Control Program Guide and Reference" and document the 32-bit APIs with the names that will be used by developers, not the internal names that you find in the DLLs.

When IBM implemented the 32-bit version of OS/2, the 16-bit version already existed. To allow the APIs to co-exist, all the 32-bit versions, TTBOMK, include a 32 in the internal name (i.e. Dos32Open). The external name used by developers is still DosOpen and the linker takes care of translating DosOpen to Dos32Open.

In most cases, the prototypes for the 32-bit and 16-bit versions of an API are identical. The sizes of the parameters might differ, but in many cases the compiler takes care of the messy details making sure that the passed parameters are the right size. In the cases where the parameters differ, you want to show both prototypes.

Also, you will find that developers just starting on a new platform will need to learn the names of the .lib files needed to link their applications. The .dll name is typically not enough because many DLLs contain only ordinals and the LIB files define the API name to ordinal conversion. 

Martini (talk) 15:15, 9 June 2016 (CEST) Also



Perhaps I did not state things clearly. The APIs listed in "Control Program Guide and Reference" are the APIs that will have a 32 in the internal name. What I was trying to say is that a developer does not need to consider the internal name except in rare cases so it's better to document the APIs in terms of there external names. 

Temporary conclusion: There is no need to put the function with the 16 or 32 on it. The developer (except for some exception) should not call the functions with the number.

There are some exceptions that will need to be on the CPI API page like:
 * Dos16QueryModFromCS - Included on the Addendum of OS2TK45. No reference to the call without the number.
 * Dos16SysTrace - Included on the Addendum of OS2TK45. No reference to the call without the number.

Issue 2 - The Non-existing Functions
There is also reported that there are functions listed on the CP1.INF documentation, but those functions can not be found on the headers to be used by developers. This is based on the OS2TK45 files.

Some examples are:
 * VioScrollDown
 * VioScrollLeft
 * VioScrollRight

This functions only exists documented on CP1.INF but no .h file names its.

Idea: To put some warning inside these functions about this issue, and add some little comments on the CPI API page, at the side of each one.