OS2 World Community Forum

OS/2, eCS & ArcaOS - Technical => Programming => Topic started by: Martin Iturbide on April 08, 2025, 02:43:12 pm

Title: EDM/2 - The API Project - Undocumented
Post by: Martin Iturbide on April 08, 2025, 02:43:12 pm
Hello

I want to ask a little help here. I found this undocumented functions and I want to see if we can document those on the EDM/2 wiki.

1) DrgQueryFormat
Ref: https://www.edm2.com/index.php/OS/2_DLL_Entry_Points_Cross_Reference
- PMCTLS.107

2) DrgGetClipPS
Ref: https://www.edm2.com/index.php/OS/2_DLL_Entry_Points_Cross_Reference
- PMCTLS.108    PMDRAG.76

I want to provide as close as possible a documentation like this function as sample (https://www.edm2.com/index.php/DrgDrag), syntax, parameters, etc.. just what we can find out.

Thanks in advance.

Regards
Title: Re: EDM/2 - The API Project - Undocumented
Post by: Lars on April 09, 2025, 05:47:55 pm
"DrgQueryFormat", as a starter: https://www.gladir.com/CODER/COS2/drgqueryformat.htm

ULONG DrgQueryFormat(PDRAGITEM dragItem, PCSZ a, ULONG b, PCSZ c, ULONG d);

Translation: "This function allows to query the data format of a drag operation."

The fun part will be to find out what "a", "b", "c", "d" stand for. I would suspect that "b" is the buffer size of string "a" and "d" is the buffer size of string "c".
My gut feeling is that this function is replaced by functions "DrgQueryNativeRMF" and "DrgQueryNativeRMFLen" plus possibly "DrgQueryTrueType" and "DrgQueryTrueTypeLen".


Title: Re: EDM/2 - The API Project - Undocumented
Post by: Martin Iturbide on April 09, 2025, 07:01:02 pm
Thanks Lars.

Here in spanish we say "something is something", which also means "everything counts".

I had created the page with the corresponding warning first:

- https://www.edm2.com/index.php/DrgQueryFormat

Regards
Title: Re: EDM/2 - The API Project - Undocumented
Post by: Martin Iturbide on April 09, 2025, 07:03:33 pm
Hello

The github search (https://github.com/search?q=DrgQueryFormat&type=code) can help me a little bit.

I found:
Quote
   ULONG APIENTRY DrgQueryFormat(PDRAGITEM pditem,
                                 PCSZ  pszAppMech,
                                 ULONG cbBuffer,
                                 PCSZ  pBuffer,
                                 ULONG ulFMTIndex);

Source (https://github.com/OS2World/DEV-SAMPLES-IBM_Dev_Toolkit_Samples/blob/b61beeafb1baec2d2ab3ff46ca90c0eb4d576986/h/pmstddlg.h#L1021).
Title: Re: EDM/2 - The API Project - Undocumented
Post by: Martin Iturbide on April 09, 2025, 07:10:28 pm
2) DrgGetClipPS
Ref: https://www.edm2.com/index.php/OS/2_DLL_Entry_Points_Cross_Reference
- PMCTLS.108    PMDRAG.76

I only found this on the OS2World Github,
Quote
HPS   APIENTRY DrgGetClipPS(HWND hwnd,               // Not yet in PMWIN.H
                            HWND hwndClip,
                            ULONG fl);
Source (https://github.com/OS2World/DEV-SAMPLES-Personal-Systems-Magazine/blob/d5c60a8203a5e5d3684c160d5264f2c9442c394a/hello/sample/pubutils/focuslib.cpp#L54).

-- https://www.edm2.com/index.php/DrgGetClipPS
Title: Re: EDM/2 - The API Project - Undocumented
Post by: Martin Iturbide on May 14, 2025, 05:03:33 pm
Hello

I had finally republished (Courtesy of IBM) this two books on the EDM/2 (in wiki format) :
- Presentation Manager Programming Guide and Reference (https://www.edm2.com/index.php/Presentation_Manager_Programming_Guide_and_Reference)
- Graphics Programming Interface (GPI) Guide and Reference (https://www.edm2.com/index.php/GPI_Guide_and_Reference)

Maybe there is no much interest because we already have online sources or the INF files, but it was useful also to have more information on the "The OS/2 API Project (https://www.edm2.com/index.php/The_OS/2_API_Project)" inside the wiki.

There had been also interesting to find the "undocumented" API functions and try to find whatever information about it.

These last days I had been using AI (Gemini and Grok) to help me out create the wiki layout in a faster way from the IPF source.
So, a quality check will be also useful if someone cares.

Regards
Title: Re: EDM/2 - The API Project - Undocumented
Post by: Martin Iturbide on May 16, 2025, 04:15:20 am
Hello

I was checking the "Programming Guide and Reference Addendum (https://www.edm2.com/index.php/Programming_Guide_and_Reference_Addendum)".

On "Device Helper (DevHlp) Services and Function Codes (https://www.edm2.com/index.php/ProgAddedum_-_Device_Helper_(DevHlp)_Services_and_Function_Codes)" there is this one that I can not find:
- DevHlp_FileOpen
The strange thing is that is list the same code, 7Fh, than "DevHlp_OpenFile" that is on the same page.  Does this "DevHlp_FileOpen" exists or it is a mistake?

On " APIs Supporting High Memory Objects (https://www.edm2.com/index.php/ProgAddedum_-_APIs_Supporting_High_Memory_Objects)" there are two functions I can not find:
- DosQueryPageUsage
- DosOpenMutexWaitSem
Are those mistakes or the documentation is available somewhere else ?

Thanks in advance for any tip or info.

Regards
Title: Re: EDM/2 - The API Project - Undocumented
Post by: Dave Yeo on May 16, 2025, 07:25:58 am
Out of curiosity, I grepped x:\os2 for all 4 functions, nothing seems to use them. Or they're called by ordinal.
I also grepped \os2tk45. Found DosQueryPageUsage() only in os2386.lib, so a real function not prototyped. Also found DevHlp_OpenFile() in inc\devhlp.inc. Take a look at the inc for cardinal(?) and comment.
All but DevHlp_FileOpen are also in addendum.inf. I'd assume DevHlp_FileOpen is a typo with OpenFile reversed, a typo I could see making.
Title: Re: EDM/2 - The API Project - Undocumented
Post by: Rich Walsh on May 16, 2025, 05:53:28 pm
- DosOpenMutexWaitSem

DosOpenMuxWaitSem
Title: Re: EDM/2 - The API Project - Undocumented
Post by: Martin Iturbide on May 16, 2025, 08:06:07 pm
Thanks for the feedback.

What I understand is that:
1) DosQueryPageUsage - Exists, but it is undocumented.
2) DevHlp_FileOpen is a typo for "DevHlp_OpenFile"
3) DosOpenMutexWaitSem is typo for "DosOpenMuxWaitSem"

Regards
Title: Re: EDM/2 - The API Project - Undocumented
Post by: Dave Yeo on May 17, 2025, 04:59:22 am
DosOpenMutexWaitSem is the one in the Programming Guide and Reference Addendum, under Additional APIs Supported in Warp Serever for e-business, so not a typo.
Title: Re: EDM/2 - The API Project - Undocumented
Post by: Rich Walsh on May 17, 2025, 08:28:26 am
DosOpenMutexWaitSem is the one in the Programming Guide and Reference Addendum, under Additional APIs Supported in Warp Serever for e-business, so not a typo.

??? That item _is_ the typo in question.

Compare the sequence of functions in that listing with those in the Control Program Guide and Reference. Where the Addendum has DosOpenMutexWaitSem, the more authoritative CP Ref has DosOpenMuxWaitSem.
Title: Re: EDM/2 - The API Project - Undocumented
Post by: Dave Yeo on May 17, 2025, 05:39:12 pm
DosOpenMutexWaitSem is the one in the Programming Guide and Reference Addendum, under Additional APIs Supported in Warp Serever for e-business, so not a typo.

??? That item _is_ the typo in question.

Compare the sequence of functions in that listing with those in the Control Program Guide and Reference. Where the Addendum has DosOpenMutexWaitSem, the more authoritative CP Ref has DosOpenMuxWaitSem.

OK, I made a typo when grepping for DosOpenMuxWaitSem. Now I see it in 3 inf's and prototyped in bsedos.h.
Thanks for the correction
Title: Re: EDM/2 - The API Project - Undocumented
Post by: Martin Iturbide on May 17, 2025, 07:17:43 pm
Hello. Thanks for the feedback.

For the moment I'm creating this page as draft to remember this conversation.
-- https://www.edm2.com/index.php/IBM_SDK/TK_Errata_Sheet (https://www.edm2.com/index.php/IBM_SDK/TK_Errata_Sheet)

Regards
Title: Re: EDM/2 - The API Project - Undocumented
Post by: Martin Iturbide on May 17, 2025, 07:37:45 pm
Hello

Andreas made a correction on the EDM/2 wiki, but I don't think it is right. He changed that "WinHSWITCHfromHAPP" should be "WinHSwitchFromHapp"  (case change).
I personally do not think it is right. The references that I have is that when OSFree tries to clone the files it uses  "WinHSWITCHfromHAPP", the PMSHAPI.DLL entry points, and the "Programming Guide and Reference Addendum" guide.

Can you help me to find out which is the correct case?

Regards
Title: Re: EDM/2 - The API Project - Undocumented
Post by: Dave Yeo on May 18, 2025, 01:57:57 am
Seems it is uppercased internally anyways.
Title: Re: EDM/2 - The API Project - Undocumented
Post by: Martin Iturbide on May 18, 2025, 05:45:29 pm
Hello

I have a confusion about Device Helper naming.

I don't know if they should be named (for example) "DevHelp_DeRegister" or "DevHlp_DeRegister" (without the 'e')

DevHelp Reference
- https://www.edm2.com/index.php/Physical_Device_Driver_(DevHlp)_Functions
- https://www.edm2.com/index.php/PDDREF:Device_Helper_(DevHlp)_Services

DevHlp Reference
- https://www.edm2.com/index.php/List_of_DevHlp_Functions

I'm searching source source code samples on github/os2world and seems that both are used. Are both fine?

Regards
Title: Re: EDM/2 - The API Project - Undocumented
Post by: Dave Yeo on May 18, 2025, 06:54:06 pm
Code: [Select]
G:\os2tk45>grep -ir devhelp_ *
h/entry.h:  int    (*DevHelp_OpenEventSem)();
h/entry.h:  int    (*DevHelp_SemHandle)();
h/entry.h:  int    (*DevHelp_PostEventSem)();
h/entry.h:  int    (*DevHelp_CloseEventSem)();
h/pddentry.h:extern void DevHelp_RegisterPDD(char *PDD_Name, void *PDD_Function);
h/pddentry.h:extern void *DevHelp_DynamicAPI(short Parm_Count, void *Worker);

Code: [Select]
G:\os2tk45>grep -ir devhlp_ * > out
grep.exe: book/addendum.inf: binary file matches
grep.exe: book/cp2.inf: binary file matches
grep.exe: book/sg244640.inf: binary file matches
grep.exe: write error: Disk full

Which is weird as "G:\os2tk45>grep -ir devhlp_ * | less" shows a few hundred hits. Actually, 158 hits.

Title: Re: EDM/2 - The API Project - Undocumented
Post by: Steven Levine on May 19, 2025, 12:49:16 am
Hi,

The Device Helpers interface naming is inconsistent for historical reason.  There is no one base reference for the Device Helpers interface.  If you are going to pick a reference doc to start with, I recommend pdd.ref from the DDK.  For sources, the the DDK headers are the place to start.

You will find references that match "Device Helpers", DeviceHelp, DevHelp, DevHlp and a few others.

As you found, there are some references in the Toolkit sources, but they are far from complete and, TTBOMK, were never used to write device drivers.

Part of the potential confusion is that the Device Helpers are not API functions per se, but rather a set of request codes and data structures passed to a single function.  The kernel passes a pointer to this function to the driver when it passes control a driver for the first time.

What you are finding with functions like DevHelp_RegisterPDD(char *PDD_Name, void *PDD_Function); are bindings defined in various header files that make it easier to call the DevHlp consistently for a given request.  The bindings are available in various forms for various compilers and assemblers.  From the DDK, there's devhlp.lib and the associated devhlp.h.   There's also devhelp.h with a set of OpenWatcom macros.
Title: Re: EDM/2 - The API Project - Undocumented
Post by: Martin Iturbide on May 19, 2025, 02:15:12 pm
Thanks for the feedback Steven.

I will be checking devhlp.lib and devhlp.h to get a better idea. It is good to know this inconsistency is for historical reasons.

Regards
Title: Re: EDM/2 - The API Project - Undocumented
Post by: Martin Iturbide on May 19, 2025, 04:56:53 pm
Hello

I also forgot to clarify my intention or what I want to accomplish.

On the EDM/2 wiki you can link thing to other wiki pages. So when I want to link some specifics "Device Helpers", I get the issue should I standardize the names to "DevHlp_" or "DevHelp_".

I haven't decided yet.

Regards
Title: Re: EDM/2 - The API Project - Undocumented
Post by: Martin Iturbide on May 19, 2025, 05:14:12 pm
Hello

On this page: https://www.os2.kr/komh/os2books/smpadd-19970312/046_L2_HighMemorySupportFun.html

There is listed "DosQueryState", and I can not find any reference to that function. I don't think it exists.

Do you think it may be a typo ? Maybe it is "DosQueryMemState"  because it is after "DosQueryMem"???

Regards
Title: Re: EDM/2 - The API Project - Undocumented
Post by: Steven Levine on May 20, 2025, 09:14:00 am
I agree that it appears to be a typo.  I was thinking it might have been DosQuerySysState, but since the list is somewhat ordered DosQueryMemState is probably more likely.
Title: Re: EDM/2 - The API Project - Undocumented
Post by: Martin Iturbide on May 22, 2025, 03:09:56 am
Hello again.

It still spins on my head if I should do something with the DevHelp_ stuff on the EDM/2.
1) Maybe it is more comfortable to standardize it as DevHelp_ since most of the items listed are that way (https://www.edm2.com/index.php/Category:DevHlps).
or
2) Just leave it that way, and redirect the different names between DevHelp_ and DevHlp_

And:
3) My other issue is that republishing the SMP Addendum there is the STRACE page when it lists the DevHelp and are some that I do not have. You can check it out here with red color on this page (https://www.edm2.com/index.php/SMPProgAdd_-_STRACE_-_DevHlp_Functions).

Regards
Title: Re: EDM/2 - The API Project - Undocumented
Post by: Steven Levine on May 22, 2025, 08:49:11 am
It really depends on what your goals are.  In general, you will find that the DevHelp prefix is used for C language bindings and DevHlp is used for Assembler bindings.

You can see this pattern if you look at your:

  https://www.edm2.com/index.php/DevHelp_ProcBlock

which looks to me as if it came from pdd.ref.

Notice also that the Assembler bindings are listed before the C bindings implying that they are more likely of more interest.  This is part of history. The kernel and device drivers were originally written in assembler.  It was only later that C became more widely used for device driver development and kernel development.  It would not surprise me if an early version of pdd.ref only documented the Assembler bindings.

This evolution shows up in early books such as Ed Iacobucci's "OS/2 Programmer's Guide" which discusses writing applications in C and Pascal, but all the examples are in Assembler.

The items in red are another case of inconsistent naming.  DevHlp_SortReqPacket is really DevHlp_SortRequest or DevHelp_SortRequest which is in the wiki.  FWIW, DevHlp_SortReqPacket is a better name for the request, but it appears IBM never got around to updating all the references DevHelp_SortRequest, assuming that was the plan.
Title: Re: EDM/2 - The API Project - Undocumented
Post by: Martin Iturbide on May 22, 2025, 10:09:32 pm
Thanks for the feedback

My goal right now it to link the DevHelp services related pages on the EDM/2 wiki, so the user can jump from an article to the DevHelp service. 

I'm thinking that I will standarize the article/page names (just the name) to DevHlp_ since it is most used way in IBM documentation, but I will do it little by little.

Thanks for the help with the names that had changed, here it what I had found for the moment, corrections are welcome.

SMPProgAdd - STRACE     || PDDREF:Device Helper (DevHlp)
DevHlp_PushReqPacket    -  DevHlp_PushRequest
DevHlp_PullReqPacket    -  DevHlp_PullRequest
DevHlp_SortReqPacket    -  DevHelp_SortRequest
DevHlp_MonCreate       -  DevHlp_MonitorCreate
DevHlp_AddTraceEvent    -  = DevHlp_SysTrace = DevHlp_RAS
DevHlp_ABIOSGetParms    -  Not found in pddref.inf
DevHlp_Profiling Kernel       - Not found in pddref.inf
DevHlp_RegStackUsage    -  DevHlp_RegisterStackUsage
DevHlp_LogEntry        -  Not found in pddref.inf
DevHlp_SaveMessage    -  DevHlp_Save_Message
DevHlp_ReallocSeg       -  DevHlp_SegRealloc
DevHlp_PutWaitingQueue    - Not found in pddref.inf
DevHlp_GetWaitingQueue    - Not found in pddref.inf


Compare sources:
- https://www.edm2.com/index.php/PDDREF:Device_Helper_(DevHlp)_Services    From pddref.inf
- https://www.edm2.com/index.php/SMPProgAdd_-_STRACE_-_DevHlp_Functions

EDM/2 Lists:
- https://www.edm2.com/index.php/Category:DevHlps
- https://www.edm2.com/index.php/List_of_DevHlp_Functions

Regards

Title: Re: EDM/2 - The API Project - Undocumented
Post by: Lars on May 27, 2025, 01:47:34 pm
DevHlp_AddTraceEvent    -  Not found in pddref.inf

DevHlp_AddTraceEvent = DevHlp_SysTrace = DevHlp_RAS
Title: Re: EDM/2 - The API Project - Undocumented
Post by: Martin Iturbide on May 27, 2025, 02:38:53 pm
DevHlp_AddTraceEvent    -  Not found in pddref.inf

DevHlp_AddTraceEvent = DevHlp_SysTrace = DevHlp_RAS

Thanks Lars. I think that it makes sense on the wiki to unify the pages for DevHlp_AddTraceEvent (https://www.edm2.com/index.php/DevHlp_AddTraceEvent) , DevHlp_SysTrace (https://www.edm2.com/index.php/DevHlp_SysTrace), DevHlp_RAS (https://www.edm2.com/index.php/DevHelp_RAS), and clearly specify that the three are the same one.

But which one should be the final name? (There is not an straight right answer, its more like a suggestions)  :D

DevHlp_AddTraceEvent was the last name used by IBM on the SMP Addedum (I guess), but I don't know if it is the right choice.

Regards


Title: Re: EDM/2 - The API Project - Undocumented
Post by: Steven Levine on May 27, 2025, 08:42:25 pm
My choice would be DevHlp_RAS for assembler usage and for DevHelp_RAS for C usage because these are what you will find in pdd.ref and the DDK sources.

FWIW, the references you found to DevHlp_AddTraceEvent and DevHlp_SysTrace in the SMP Addendum are not Device Help definitions.

DevHlp_AddTraceEvent is the description the writer chose for Hook ID 61/34 which represents a location in the kernel code.  I've yet to find any actual Device Helper related code that actually uses this symbol.

DevHlp_SysTrace is part of a comment in the assembly language example for dh_PerfSysTrace.  Again, I've yet to find any actual Device Helper related code that actually uses this symbol.

It probably cannot hunt to mention these alternative references to DevHlp_RAS and DevHelp_RAS, although I'm not sure how I would describe why they exist.
Title: Re: EDM/2 - The API Project - Undocumented
Post by: Martin Iturbide on May 27, 2025, 09:12:06 pm
Hello Steven.

You know more than me on this area.
My references are:
1) DevHlp_AddTraceEvent
-- "SMP Programming Addendum" on the "STRACE - DevHlp Functions (https://www.os2.kr/komh/os2books/smpadd-19970312/515_L3_DevHlpFunctions2of2.html)"

-- sg244640: "Trace Events for DEVHELP Major Code: 0X0006, Sorted by Tracepoint (https://www.os2.kr/komh/os2books/os2tk45/sg244640/991_L4_TraceEventsforDEVHEL.html)"
--- OS) DevHlp_AddTraceEvent Post-Invocation 00132 (0X0084)
--- OS) DevHlp_AddTraceEvent Pre-Invocation 00004 (0X0004)


2) DevHlp_SysTrace
-- "Programming Guide and Reference Addendum"  on the "Device Helper (DevHlp) Services and Function Codes" at "DevHlp_SysTrace (https://www.os2.kr/komh/os2books/os2tk45/addendum/020_L2_DevHlp_SysTrace.html)".

There it says "DevHlp_SysTrace is synonymous with DevHlp_RAS."

On "devhlp.inc" from the DDK it has:
Quote
DevHlp_RAS              EQU     40      ; 28    Put info in RAS trace buffer
DevHlp_SysTrace         EQU     40      ; 28    Synonym for DevHlp_RAS   f180062

This is why I guess that DevHlp_RAS and DevHlp_SysTrace  are the same. No idea about "DevHlp_AddTraceEvent".

Regards

Title: Re: EDM/2 - The API Project - Undocumented
Post by: Lars on May 28, 2025, 11:34:41 am
Hello Steven.

You know more than me on this area.
My references are:
1) DevHlp_AddTraceEvent
-- "SMP Programming Addendum" on the "STRACE - DevHlp Functions (https://www.os2.kr/komh/os2books/smpadd-19970312/515_L3_DevHlpFunctions2of2.html)"

-- sg244640: "Trace Events for DEVHELP Major Code: 0X0006, Sorted by Tracepoint (https://www.os2.kr/komh/os2books/os2tk45/sg244640/991_L4_TraceEventsforDEVHEL.html)"
--- OS) DevHlp_AddTraceEvent Post-Invocation 00132 (0X0084)
--- OS) DevHlp_AddTraceEvent Pre-Invocation 00004 (0X0004)


2) DevHlp_SysTrace
-- "Programming Guide and Reference Addendum"  on the "Device Helper (DevHlp) Services and Function Codes" at "DevHlp_SysTrace (https://www.os2.kr/komh/os2books/os2tk45/addendum/020_L2_DevHlp_SysTrace.html)".

There it says "DevHlp_SysTrace is synonymous with DevHlp_RAS."

On "devhlp.inc" from the DDK it has:
Quote
DevHlp_RAS              EQU     40      ; 28    Put info in RAS trace buffer
DevHlp_SysTrace         EQU     40      ; 28    Synonym for DevHlp_RAS   f180062

This is why I guess that DevHlp_RAS and DevHlp_SysTrace  are the same. No idea about "DevHlp_AddTraceEvent".

Regards

Looks like we are spinning around in circles:

you will realize that major trace code 0x0006 neither lists DevHlp_RAS nor DevHlp_SysTrace. That said, it looks like DevHlp_AddTraceEvent = DevHlp_RAS = DevHlp_SysTrace as that is what this devhelp does: it adds a trace event to the trace buffer.