HP 3000 Manuals HP 3000 Manuals
Using the System Programming Extensions
The system programming extensions in this COBOL system permit COBOL
programs to access all Motif features. (Note that it is not possible to
produce a Motif application using purely X/Open compliant COBOL code.)
These extensions include:
* CALL...USING BY VALUE literal SIZE n
* CALL...USING...RETURNING...
* ENTRY...USING BY VALUE...
* EXIT PROGRAM RETURNING...
* USAGE POINTER
* USAGE PROCEDURE-POINTER
* SET...TO ENTRY...
* LOCAL-STORAGE SECTION
* Recursion
* Concatenation
Calling the Motif API
Motif uses the C language parameter-passing convention just the same as
Micro Focus COBOL running under UNIX. So for Motif applications, the
CALL-CONVENTION clause in the Special-Names paragraph should either not
be used or should specify the default COBOL call-convention value of 0.
Returning Values from Motif API Functions
The RETURNING phrase on a CALL statement stores the value returned by a
Motif API function. For example:
01 root-widget pic x(4) comp-5.
...
call "XtInitialize" using "demo" & x"00",
"demo" & x"00", by value 0, 0,
by reference argc, argv
returning root-widget
This stores the result returned from the API function XtInitialize in the
data item root-widget.
Returning a Value from a COBOL Procedure
A Motif window procedure sometimes needs to return a value to the
function that called it. In COBOL, use the RETURNING phrase on the EXIT
PROGRAM statement. For example:
exit program returning mresult
Pointers
A data item declared as POINTER passes the address of another data item
to the API so that Motif can access the second data item. In the
following example the pointer args is set to point to the table all-args
so that Motif can access the table:
01 all-args occurs max-args.
03 name-tab usage pointer.
03 arg-tab pic x(4) comp-5.
01 args usage pointer.
...
set args to address of all-args ( 1 )
...
call "XmCreateMainWindow"
using by value root-widget,
by reference "mainWindow" & x"00",
by value args, nargs
returning main-window
...
Procedure Pointers
A data item declared as PROCEDURE-POINTER passes the address of a window
procedure to Motif so that it can call that procedure upon encountering a
particular event, such as "button-activated" in the following example:
01 proc-pointer usage procedure-pointer.
...
linkage section.
01 ba-widget pic x(4) comp-5.
01 ba-client usage pointer.
01 ba-call usage pointer.
...
* Add a callback so we can tell when the button has been pressed
set proc-pointer to entry "button-activated"
call "XtAddCallback" using by value push-button,
by reference XmNactivateCallback,
by value proc-pointer, 0
...
entry "button-activated" using ba-widget, ba-client, ba-call
* We get here when the push button has been pressed.
call "XtManageChild" using by value message-box
...
Local-Storage Section
By default, all COBOL variables are global; that is, any variable defined
in the Working-Storage Section can be referenced from any other section
of the program. This COBOL system lets you create variables that are
local to a particular invocation of a procedure; these variables can be
referenced only within that procedure. These variables are created on
the stack when a procedure using them is called, then discarded when the
procedure terminates. You define these variables in the Local-Storage
Section.
If you use global variables in a recursive procedure, each new procedure
invocation references the same storage location for a particular variable
name, overwriting information stored there by previous invocations. The
Local-Storage Section eliminates this problem by creating an individual
set of procedure variables for each invocation. Use local variables when
writing recursive procedures (see the chapter Writing Programs).
Indirect recursion occurs when a procedure invokes Motif, which in turn
calls that procedure, perhaps through an alternate entry point. Although
it is indirect, this recursion can still overwrite variables, including
system ones such as the PERFORM return addresses, that should remain
distinct for each invocation. Therefore, you should always declare a
Local-Storage Section in a Motif application and declare any variables
there unless you are certain that it is truly global and does not change
between invocations of a procedure.
Sample Program
The sample program motdemo included with this system shows how to write a
simple Motif program in COBOL. It demonstrates the following Motif
features:
* A standard window
* Menu bar and pull-down menu
* Push button
* Message box
* Automatic window repositioning and resizing