Talk:Control Program Functions

From EDM2
Revision as of 12:51, 14 September 2017 by Martini (Talk | contribs)

(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to: navigation, search

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.