PL/I for Windows

IBM documentation on this product seems to be substandard (read:
sucks). I'm trying to find an example and description of a windowed
PL/I application. In OS/2 we'd call it a Presentation Manager
Application, I don't know what the corresponding windows term is. The
Language Reference and Programmer's Guide don't seem to have what I'm
looking for. There has to be better information. If anyone is writing
this kind of program, what did you use? Can anyone point me to sample
code? Thanks.

Peter_Flass@yahoo.com wrote:
> IBM documentation on this product seems to be substandard (read:
> sucks). I'm trying to find an example and description of a windowed
> PL/I application. In OS/2 we'd call it a Presentation Manager
> Application, I don't know what the corresponding windows term is. The
> Language Reference and Programmer's Guide don't seem to have what I'm
> looking for. There has to be better information. If anyone is writing
> this kind of program, what did you use? Can anyone point me to sample
> code? Thanks.

I would not expect such information in the LRM at all. At least for Personal PL/I for
OS/2, the product comes with a SAMPLES directory which includes two examples, PMDEMO
and PMDEMO2, which use a PM window. It was necessary to add the LIBS(MULTI) option
and use EXECMODE to select single processor operation to get PMDEMO2 to run. The PG
includes a section which explains the PMDEMO2 example.

The examples are pretty simple minded but get you started.

There are problems to be overcome using the supplied include libraries. Rather than
directly declaring everything as it would be best done in PL/I, the preprocessor is
used to replace the C names for various datatypes with PL/I equivalents. For
example, if you use the byte or bool builtin function you will be in for an
unpleasant surprise.

The toolkit has documentation of the OS/2 API calls. You can work out from that how
to declare each API entry point and the relevant data structures. There is no need
to use the supplied include libraries at all. I have no idea what you would use with
doze.

Also by replacing the version of os2386.lib that came with Personal PL/I with the
version in the toolkit I was able to get large file support working.

James J. Weinkam wrote:
> Peter_Flass@yahoo.com wrote:
>
>> IBM documentation on this product seems to be substandard (read:
>> sucks). I'm trying to find an example and description of a windowed
>> PL/I application. In OS/2 we'd call it a Presentation Manager
>> Application, I don't know what the corresponding windows term is. The
>> Language Reference and Programmer's Guide don't seem to have what I'm
>> looking for. There has to be better information. If anyone is writing
>> this kind of program, what did you use? Can anyone point me to sample
>> code? Thanks.
>
>
> I would not expect such information in the LRM at all. At least for
> Personal PL/I for OS/2, the product comes with a SAMPLES directory which
> includes two examples, PMDEMO and PMDEMO2, which use a PM window. It was
> necessary to add the LIBS(MULTI) option and use EXECMODE to select
> single processor operation to get PMDEMO2 to run. The PG includes a
> section which explains the PMDEMO2 example.
>
> The examples are pretty simple minded but get you started.
>
> There are problems to be overcome using the supplied include libraries.
> Rather than directly declaring everything as it would be best done in
> PL/I, the preprocessor is used to replace the C names for various
> datatypes with PL/I equivalents. For example, if you use the byte or
> bool builtin function you will be in for an unpleasant surprise.
>
> The toolkit has documentation of the OS/2 API calls. You can work out
> from that how to declare each API entry point and the relevant data
> structures. There is no need to use the supplied include libraries at
> all. I have no idea what you would use with doze.
>
> Also by replacing the version of os2386.lib that came with Personal PL/I
> with the version in the toolkit I was able to get large file support
> working.

Thanks James. I didn't expect the LRM to have any information, but
perhaps the Programmer's Guide, or maybe an addendum. I have gotten
about to the same point with OS/2 1.0, but have been frustrated by the
lack of good documentation. There are two procedure options WINMAIN,
which is somewhat documented, and WINPROC, which is prtty
self-expanatory but undocumented. My window procedure didn't seem to ba
able to access STATIC storage declared elsewhere in the package.

At any rate, I had hoped Windows versions later than 1.0 would be better
documented than what I have. I'm playing around with getting PM support
into Iron Spring PL/I, and would like to keep the syntax and semantics
consistent with IBM compilers, minus the preprocessor usage.

Peter Flass wrote:
> James J. Weinkam wrote:
>> Peter_Flass@yahoo.com wrote:
>>
>>> IBM documentation on this product seems to be substandard (read:
>>> sucks). I'm trying to find an example and description of a windowed
>>> PL/I application. In OS/2 we'd call it a Presentation Manager
>>> Application, I don't know what the corresponding windows term is. The
>>> Language Reference and Programmer's Guide don't seem to have what I'm
>>> looking for. There has to be better information. If anyone is writing
>>> this kind of program, what did you use? Can anyone point me to sample
>>> code? Thanks.
>>
>>
>> I would not expect such information in the LRM at all. At least for
>> Personal PL/I for OS/2, the product comes with a SAMPLES directory
>> which includes two examples, PMDEMO and PMDEMO2, which use a PM
>> window. It was necessary to add the LIBS(MULTI) option and use
>> EXECMODE to select single processor operation to get PMDEMO2 to run.
>> The PG includes a section which explains the PMDEMO2 example.
>>
>> The examples are pretty simple minded but get you started.
>>
>> There are problems to be overcome using the supplied include
>> libraries. Rather than directly declaring everything as it would be
>> best done in PL/I, the preprocessor is used to replace the C names for
>> various datatypes with PL/I equivalents. For example, if you use the
>> byte or bool builtin function you will be in for an unpleasant surprise.
>>
>> The toolkit has documentation of the OS/2 API calls. You can work out
>> from that how to declare each API entry point and the relevant data
>> structures. There is no need to use the supplied include libraries at
>> all. I have no idea what you would use with doze.
>>
>> Also by replacing the version of os2386.lib that came with Personal
>> PL/I with the version in the toolkit I was able to get large file
>> support working.
>
> Thanks James. I didn't expect the LRM to have any information, but
> perhaps the Programmer's Guide, or maybe an addendum. I have gotten
> about to the same point with OS/2 1.0, but have been frustrated by the
> lack of good documentation. There are two procedure options WINMAIN,
> which is somewhat documented, and WINPROC, which is prtty
> self-expanatory but undocumented. My window procedure didn't seem to ba
> able to access STATIC storage declared elsewhere in the package.

The window procedure must be non nested. As such, it can only refer to variables,
static or otherwise, declared within itself or in the package outside of any
procedure (these are inherently static). To refer to variables in other procedures
they would have to be external and declared in both procedures. Can you be more
specific about the problems you are having addressing static storage?
>
> At any rate, I had hoped Windows versions later than 1.0 would be better
> documented than what I have. I'm playing around with getting PM support
> into Iron Spring PL/I, and would like to keep the syntax and semantics
> consistent with IBM compilers, minus the preprocessor usage.
>
This doesn't really have anything to do with the syntax and semantics of anything
within PL/I per se beyond its ability to support all the types of call linkage and
data types needed to invoke API procedures. The OS/2 compiler certainly does this and
Personal PL/I for windows also does as far as I can tell from the manual (which is
common to both products), so all you have to do is read up the API calls you need for
your application and declare the entry points and data structures accordingly. The
OS/2 PM API calls are documented in the toolkit. I have no idea where corresponding
information for windows can be found, but presumably it would come from Microsoft.

Here are the various linkage conventions supported by Personal PL/I. The other PC
PL/I products probably provide even more extensive support for calling non PL/I software.

----------------------------------

LINKAGE (Workstation only)
This option specifies the calling convention used.

CDECL
This option specifies the CDECL linkage convention used by 32-bit C compilers. You
can specify CDECL in OPTIONS in PROCEDURE statements and ENTRY declarations.

CDECL16 (OS/2 only)
This option specifies the CDECL linkage convention used by the IBM C/2 and Microsoft
C Version 6.0 compilers. You can specify CDECL16 in OPTIONS in PROCEDURE statements
and ENTRY declarations.

FASTCALL16 (OS/2 only)
This option specifies the FASTCALL linkage convention used by the Microsoft C Version
6.0 compiler. You can specify FASTCALL16 only in OPTIONS in ENTRY declarations.

OPTLINK (OS/2)
This option is the default, and is the fastest linkage convention. It is not standard
for all OS/2 applications. If you specify this option, it is tolerated by systems
other than OS/2.

PASCAL16 (OS/2 only)
This option specifies the PASCAL linkage convention used by the IBM C/2 and Microsoft
C Version 6.0 compilers. You can specify PASCAL16 in OPTIONS in PROCEDURE statements
and ENTRY declarations.

STDCALL (Windows Only)
This option specifies the STDCALL linkage which is the standard linkage convention
used by all Windows APIs. You can specify STDCALL in OPTIONS in PROCEDURE statements
and ENTRY declarations.

SYSTEM (OS/2)
This option is the calling convention which should be used for calls to the operating
system. Although this option is slower than OPTLINK, it is standard for all OS/2
applications and is used for calling OS/2 application programming interfaces. If you
specify this option, it is tolerated by systems other than OS/2.

For more information about calling conventions, refer to the Programming Guide.

---------------------------------

Here is some information from the PG about the STDCALL linkage used by windows:

---------------------------------

The following rules apply to the STDCALL calling convention:

oAll parameters are passed on the stack.

oThe parameters are pushed onto the stack in a lexical right-to-left order.

oThe called function removes the parameters from the stack.

oFloating point values are returned in ST(0), the top register of the floating point
register stack. Functions returning aggregate values return them as follows: hermhi=0
headhi=2.

Size of Aggregate Value Returned in

8 bytes EAX-EDX pair

5, 6, 7 bytes EAX The address to place the return values is passed as a hidden
parameter in EAX.

4 bytes EAX

3 bytes EAX The address to place the return values is passed as a hidden parameter to
EAX.

2 bytes AX

1 byte AL

For functions that return aggregates 5, 6, 7 or more than 8 bytes in size, the
address to place the return values is passed as a hidden parameter, and the address
is passed back in EAX.

oSTDCALL has the restriction that an unprototyped STDCALL function with a variable
number of arguments will not work.

oFunction names are decorated with an underscore prefix, and a suffix which consists
of an at sign (@), followed by the number of bytes of parameters (in decimal).
Parameters of less than four bytes are rounded up to four bytes. Structure sizes are
also rounded up to a multiple of four bytes. For example, consider a function fred
prototyped as follows:

dcl fred ext entry (fixed bin(31) byvalue, fixed bin(31) byvalue, fixed bin(15)
byvalue);

It would appear as follows in the object module:

_FRED@12



When building export lists in .DEF files, the decorated version of the name should be
used. If you use undecorated names in the DEF file, you must give the object files to
ILIB along with the DEF file. ILIB uses the object files to determine how each name
ended up after decoration.

The following examples are included for purposes of illustration and clarity only.
The examples assume that you are familiar with programming in assembler. In the
examples, the stack grows toward the bottom of the page, and ESP always points to the
top of the stack.

For the following call, a, b,and c are 32-bit integers and func has two local
variables, x and y (both 32-bit integers):

m = func(a,b,c)


The stack for the call to FUNC would look like this:
Stack

┌───────────────┠€â”€â”€â”€â”€â”€â”€â”€â”€â”� Higher Memory
│ c │
├───────────────┠€â”€â”€â”€â”€â”€â”€â”€â”€â”¤
│ b │
├───────────────┠€â”€â”€â”€â”€â”€â”€â”€â”€â”¤
│ a │
├───────────────┠€â”€â”€â”€â”€â”€â”€â”€â”€â”¤
│ caller's EIP │
├───────────────┠€â”€â”€â”€â”€â”€â”€â”€â”€â”¤
│ caller's EBP │
EBP ─────── ├───────────────┠€â”€â”€â”€â”€â”€â”€â”€â”€â”¤
│ x │
├───────────────┠€â”€â”€â”€â”€â”€â”€â”€â”€â”¤
│ y │
├───────────────┠€â”€â”€â”€â”€â”€â”€â”€â”€â”¤ ─â”�
│ Saved EDI │ │
├───────────────┠€â”€â”€â”€â”€â”€â”€â”€â”€â”¤ │ These would only be
│ Saved ESI │ │ pushed if they were
├───────────────┠€â”€â”€â”€â”€â”€â”€â”€â”€â”¤ │ used in this function.
│ Saved EBX │ │
ESP ─────── └───────────────┠€â”€â”€â”€â”€â”€â”€â”€â”€â”˜ ─┘
Lower Memory

The instructions used to create this activation record on the stack look like this on
the calling side:

PUSH c
PUSH b
PUSH a
CALL _func@12

I asked one of my "usually reliable sources" at IBM about at least adding SOME
information on Windows-GUI applications in the PL/I for Windows PG and received
the following response:

"Bill,

there are customers who have production PL/I code running on Windows, but afaik,
they are all using either Java or VisualBasic to build their GUI front-ends"

FYI,
There IS information on Java interoperability in the current PG.

As usual, YMMV!!!

--
Bill Klein
wmklein <at> ix.netcom.com
<Peter_Flass@yahoo.com> wrote in message
news:0416913f-3f68-46a6-abde-c2245ee010aa@f24g2000prh.googlegroups.com...
> IBM documentation on this product seems to be substandard (read:
> sucks). I'm trying to find an example and description of a windowed
> PL/I application. In OS/2 we'd call it a Presentation Manager
> Application, I don't know what the corresponding windows term is. The
> Language Reference and Programmer's Guide don't seem to have what I'm
> looking for. There has to be better information. If anyone is writing
> this kind of program, what did you use? Can anyone point me to sample
> code? Thanks.

On 05/28/08 02:43 pm, Peter_Flass@yahoo.com wrote:
> IBM documentation on this product seems to be substandard (read:
> sucks). I'm trying to find an example and description of a windowed
> PL/I application. In OS/2 we'd call it a Presentation Manager
> Application, I don't know what the corresponding windows term is. The
> Language Reference and Programmer's Guide don't seem to have what I'm
> looking for. There has to be better information. If anyone is writing
> this kind of program, what did you use? Can anyone point me to sample
> code? Thanks.

If you are a member of SHARE and have access to old [read: "about 3
years ago"] proceedings, there were some IBM presentations on writing
Web applications with workstation PL/I. There were samples of working
code that were used for live demos. I'd need to do some searching to
find them myself or I'd give you more specifics now.

Carl

On 05/30/08 10:05 pm, CG wrote:
> On 05/28/08 02:43 pm, Peter_Flass@yahoo.com wrote:
>> IBM documentation on this product seems to be substandard (read:
>> sucks). I'm trying to find an example and description of a windowed
>> PL/I application. In OS/2 we'd call it a Presentation Manager
>> Application, I don't know what the corresponding windows term is. The
>> Language Reference and Programmer's Guide don't seem to have what I'm
>> looking for. There has to be better information. If anyone is writing
>> this kind of program, what did you use? Can anyone point me to sample
>> code? Thanks.
>
> If you are a member of SHARE and have access to old [read: "about 3
> years ago"] proceedings, there were some IBM presentations on writing
> Web applications with workstation PL/I. There were samples of working
> code that were used for live demos. I'd need to do some searching to
> find them myself or I'd give you more specifics now.

I really should have been more specific. Rather than saying 'Web
applications' I should have said PL/I interfacing with Java and using
Java interfaces to build applications. Therefore, anything that can be
done with Java could be done with the demo PL/I code.

On Wed, 28 May 2008 23:50:52 -0400, Peter Flass
<Peter_Flass@Yahoo.com> wrote:

>James J. Weinkam wrote:
>> Peter_Flass@yahoo.com wrote:
>>

>
>At any rate, I had hoped Windows versions later than 1.0 would be better
>documented than what I have. I'm playing around with getting PM support
>into Iron Spring PL/I, and would like to keep the syntax and semantics
>consistent with IBM compilers, minus the preprocessor usage.

I just look at the Iron Spring web page (learn about a new company
every day ...). I hope I'm not being dumb here, but why only OS/2 and
not Windows 2000/XP/Vista?

-AH

CG wrote:
>>
>> If you are a member of SHARE and have access to old [read: "about 3
>> years ago"] proceedings, there were some IBM presentations on writing
>> Web applications with workstation PL/I. There were samples of working
>> code that were used for live demos. I'd need to do some searching to
>> find them myself or I'd give you more specifics now.
>
>
> I really should have been more specific. Rather than saying 'Web
> applications' I should have said PL/I interfacing with Java and using
> Java interfaces to build applications. Therefore, anything that can be
> done with Java could be done with the demo PL/I code.
>

Thanks, I think I have at lest one of these "Interfacing PL/I with JNI"
or something to that effect.

James J. Weinkam wrote:
>
> The window procedure must be non nested. As such, it can only refer to
> variables, static or otherwise, declared within itself or in the package
> outside of any procedure (these are inherently static). To refer to
> variables in other procedures they would have to be external and
> declared in both procedures. Can you be more specific about the problems
> you are having addressing static storage?
>

Thanks again James. My mention of the addressing problem was really
just an aside, I was hoping there would be more and/or better
documentation, but apparently not. Since you asked I had to look back
at the code I had been playing around with, probably a year or so ago.
I'll have to play around a bit to try to recall what was going on.

Thanks also for all the documentation.