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. 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.
For example:
VioScrollUp from CP1.INF says:
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:
VioScrollUp(TopRow, LeftCol, BotRow, RightCol, Lines, Cell, VioHandle, &rc);
In the alternative, it should be like this:
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);
VioScrollUp from prcp.inf (legacy) says:
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:
/* VIOCALLS */
#define ORD_VIOSCROLLUP 7
bsesub.h
#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.
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