topic Re: How to define arguments for callable programs written in COBOL in Operating System - OpenVMS

How to define arguments for callable programs written in COBOL

John T. Farmer — Thu, 17 Aug 2006 14:02:16 GMT

What is the proper syntax for call arguments in a called COBOL program. I wish to adhere to the standard calling procedures used by the RTL ("By Descriptor", "By Referenc" & "By Value"). I have seen that coded in COBOL where upon entering the called program, it had to resolve the variable addresses and again, upon exiting, it had to copy the information back to any return arguments. My only experience has been in passing fixed field length data on the "Procedure Division Using" line.

Thanks,

John
OpenVMS v7.2
COBOL v2.6-1060
Alpha hardware

Re: How to define arguments for callable programs written in COBOL

Hein van den Heuvel — Thu, 17 Aug 2006 14:45:11 GMT

John,

[Welcome to the HP ITRC OpenVMS Forum]

All this is nswerred in great detail in the Cobol Users Guide: "Interprogram Communication
12.4 Accessing Another Programâ s Data Division"
You can only receive by reference.
You'll have to play games (typically LIB$COPYxxxx and LIB$MOVxxx calls, or even cobol helper functions) to deal with descriptors. And "SET {pointer-id} . . . TO REFERENCE OF identifier" to get at data passed by value.

"A called COBOL subprogram must have arguments passed to it using
BY REFERENCE, which is the default, or BY CONTENT. BY VALUE,
OMITTED, and BY DESCRIPTOR are HP extensions and will not work
as expected if passed to a COBOL program. These argument-passing
mechanisms are necessary when calling Run-Time Library Routines and
system service routines as described in Chapter 13."

Good luck,
Hein.

Re: How to define arguments for callable programs written in COBOL

John T. Farmer — Thu, 17 Aug 2006 14:57:59 GMT

Hein,

Thank you for the detailed response. I have been away from VMS for about 4 years. A little rusty, but that info sounds familiar. Thanks for the doc reference.

John

Re: How to define arguments for callable programs written in COBOL

Richard J Maher — Fri, 18 Aug 2006 05:47:21 GMT

Hi John,

Attached is a COBOL example program that receives arguments BY DESCRIPTOR (or more specifically, receives Descriptors BY REFERENCE :-)

Look for the TIP_LOGON routine, and also the OUT_MSG that is called by SYS$PUTMSG with the message text passed BY DESCRIPTOR.

I don't think there's and BY VALUE passing in there but, as Hein pointed out, you just SET WS_POINTER_VAR TO REFERENCE LINKAGE_SECTION_VAR and the 32-bit value will be stuck in your pointer. (What if it's a pointer-64?)

Regards Richard Maher

Re: How to define arguments for callable programs written in COBOL

comarow — Fri, 18 Aug 2006 07:38:54 GMT

Many years ago I taught the class, Utilizing
VMS Features from Cobol. If you search the data base, there are a bunch of examples of various calls.

Search under Example-COBOL.

Re: How to define arguments for callable programs written in COBOL

John T. Farmer — Fri, 18 Aug 2006 14:13:00 GMT

I'm sorry, where would I do that search? I am new to this group.

Thanks,

John

Re: How to define arguments for callable programs written in COBOL

comarow — Fri, 18 Aug 2006 14:45:09 GMT

John,

It appears they are in an older database.
If you give me your email address I'll send you some examples, or log a call.

Bob C.

Re: How to define arguments for callable programs written in COBOL

Jan van den Ende — Fri, 18 Aug 2006 15:53:35 GMT

John,

PLEASE, no plain e-mail adresses!
It is easy enough to morph them such tat a human can reconstruct it.

These fora, like so many others, are quite popular for address-minibg!.

I wil ask a moderator to change it aASAP.

Proost.

Have one on me.

jpe

Re: How to define arguments for callable programs written in COBOL

comarow — Fri, 18 Aug 2006 16:27:32 GMT

I sent a collection of old VAX examples.
Not much has changed.

Re: How to define arguments for callable programs written in COBOL

Richard J Maher — Mon, 21 Aug 2006 09:02:55 GMT

Hi John,

Here's one I prepared earlier :-)

I knew I had a reasonable example of BY VALUE passing in COBOL so here it is. (A good example of I$CC calling also, if I do say so myself)

Good luck!

Regards Richard Maher

Re: How to define arguments for callable programs written in COBOL

John T. Farmer — Mon, 21 Aug 2006 10:07:00 GMT

Thanks to all for examples. For me, that is the best way to learn. Knocking off the rust on my COBOL skills and this is very helpful.

John

Re: How to define arguments for callable programs written in COBOL

John T. Farmer — Mon, 21 Aug 2006 16:38:34 GMT

Richard,

In the "By Descriptor" example, is it the LIB$SCOPY_DXDX call that handles size mismatches in parameters between calling and called programs?

I want to code my sub-program with, say, a 1000 byte string variable for some text manipulation. But I want the calling program to be able to define that at any lengnth 1 to 1000. No need to define 1000 byte field when I know I will only need 20 bytes in a particular main program.

See my attached examples. A1.exe works because the sizes match. A2.exe hangs. B.cob currently doesn't do anything special to resolve the size differences.

Thanks,

John

Re: How to define arguments for callable programs written in COBOL

Hein van den Heuvel — Mon, 21 Aug 2006 22:04:29 GMT

Richard,

>> In the "By Descriptor" example, is it the LIB$SCOPY_DXDX call that handles size mismatches in parameters between calling and called programs?

Yeah, but you want to focus on the STR$COPY calls IMHO.

>> I want to code my sub-program with, say, a 1000 byte string variable for some text manipulation. But I want the calling program to be able to define that at any lengnth 1 to 1000. No need to define 1000 byte field when I know I will only need 20 bytes in a particular main program.

How is the called program to know how much data to work on. You'll need to pass an explicit length in a param, or pass by descriptor and decode the descriptor, or... use a terminator: yuck!

>> . A2.exe hangs. B.cob currently doesn't do anything special to resolve the size differences.

Righth. So B will just display 1000 bytes starting at the buffer pointend to by A2, but that only points to 200 initialized values. Beyond that, it it 'pot luck'. The program will send semi-random data to the terminal, which apparently manged to hang it. The program 'hang' is just it waiting for terminal IO to finish.

Hein.

Re: How to define arguments for callable programs written in COBOL

John T. Farmer — Tue, 22 Aug 2006 07:48:55 GMT

See, what I'm getting at is, being able to write a COBOL program (like program B) using the calling mechanism like the lib$ or str$ functions. Like STR$TRIM. I don't have to match the parameters exact size. The calling program handles that. So yes, I'd like to be able to handle 'BY DESCRIPTOR' for variable sizes.

I actually did one of these years ago (using another example from our tech staff) and remembered having to do some system calls to resolve the length and copy to the actual work string inside the CALLED program.

I feel like the code I need is in one of these examples, I'm just overlooking it.

Thanks for your patience, guys...

John

Re: How to define arguments for callable programs written in COBOL

Hein van den Heuvel — Tue, 22 Aug 2006 23:09:21 GMT

No takers?

First, to 'see' what went wrong with your A2, do a $define/user sys$output a2.log.
Then $run A2
and $dump/record a2.log

---- solution 1 ----
Change the caller to call "BY DESCRITOR data-element".

Use a helper routine to de-reference the argument. The first layer, accepts the descriptor as a structure and passed on teh firrst element as the length, and then passes the VALUE of the next element which in fact is the address of the data element.
The Real McCoy, takes the low word from the length and uses that in a reference modification to the data.

IDENTIFICATION DIVISION.
PROGRAM-ID. CALLEDPROG.
DATA DIVISION.
WORKING-STORAGE SECTION.
LINKAGE SECTION.
01 DESC.
03 DESC_LENGTH PIC 9(9) COMP.
03 DESC_ADDRESS USAGE POINTER.
01 L-1000-CHAR PIC X(1000).

PROCEDURE DIVISION USING DESC.
0000.
CALL "REALMCCOY" USING DESC_LENGTH, BY VALUE DESC_ADDRESS.
EXIT PROGRAM.

-----

IDENTIFICATION DIVISION.
PROGRAM-ID. REALMCCOY.
DATA DIVISION.
WORKING-STORAGE SECTION.
LINKAGE SECTION.
01 DESC_LENGTH.
03 DESC_LENGTH_WORD PIC 9(4) COMP.
03 FILLER PIC XX.
01 L-1000-CHAR PIC X(1000).

PROCEDURE DIVISION USING DESC_LENGTH, L-1000-CHAR.
0000.
DISPLAY 'L-1000-CHAR=' L-1000-CHAR(1:DESC_LENGTH_WORD).
EXIT PROGRAM.

---- solution 2 ----
Change the caller to call "BY DESCRITOR data-element".
Now use library routines to play with the descriptor. Where thy expect an argmument by descriptor, just pass along the address of the received descriptor.

IDENTIFICATION DIVISION.
PROGRAM-ID. CALLEDPROG.
DATA DIVISION.
WORKING-STORAGE SECTION.
01 DESC_LENGTH PIC 9(9) COMP.
01 DESC_ADDRESS USAGE POINTER.
01 L-1000-CHAR PIC X(1000).

LINKAGE SECTION.
01 DESC PIC X.

PROCEDURE DIVISION USING DESC.
0000.
CALL "STR$ANALYZE_SDESC" USING BY REFERENCE DESC,
BY REFERENCE DESC_LENGTH, BY REFERENCE DESC_ADDRESS.
CALL "STR$COPY_DX" USING BY REFERENCE DESC, BY DESCRIPTOR L-1000-CHAR.
DISPLAY 'length=', DESC_LENGTH with conversion.
DISPLAY 'L-1000-CHAR=' L-1000-CHAR(1:DESC_LENGTH).

EXIT PROGRAM.

Enjoy,
Hein.

Re: How to define arguments for callable programs written in COBOL

John T. Farmer — Wed, 23 Aug 2006 12:22:02 GMT

I found the solution to be with LIB$CVT_DX_DX. See attached examples. Thanks to all for putting me on the right trail.

John

Re: How to define arguments for callable programs written in COBOL

Jan van den Ende — Wed, 23 Aug 2006 13:20:52 GMT

John,

perhaps now would be a good time to check

http://forums1.itrc.hp.com/service/forums/helptips.do?#33

and quantify your thanks to those who helped.

Proost.

Have one on me.

jpe

Re: How to define arguments for callable programs written in COBOL

Richard J Maher — Sat, 26 Aug 2006 18:49:30 GMT

Hi Hein,

I'm Richard, he's John :-)

The only thing about the STR$ versions is they they often wish to signal errors and one really shouldn't rely on cob$handler's behaviour in these circumstances. So unless you've lib$established a condition handler (or at least lib$sig_to_ret) then I'd opt for the lib$ versions.

Didn't fancy the Bruden gig?

Hi John,

Lib$cvt_dx appears to do a lot more than you were looking for but if it works for you then great.

As you've seen, you don't have to use lib$analyze_sdesc to break up the descriptor as you already have it in the Linkage Section (Some validation of what classes will be handled maybe useful)

Also, don't be afraid to subsequently pass the Linkag Section Descriptor "By Reference" to a routine that is asking for an argument "By Descriptor" (That is, you can dispense with the intermediate step of copying the string to your local WS-VAR and then passing that by descriptor.

Regards Richard Maher

PS. UPPER CASE IS NOT COMPULSORY FOR cobol

Re: How to define arguments for callable programs written in COBOL

Hein van den Heuvel — Sun, 27 Aug 2006 21:59:06 GMT

>> Hi Hein,
>> I'm Richard, he's John :-)

Ooops.

>> The only thing about the STR$ versions is >> they they often wish to signal errors and

Yeah STR$ seems the heaviest, next LIB$ then OTS$SCOPY__DXDX

>> As you've seen, you don't have to use lib$analyze_sdesc to break up the descriptor

Right, my example shows that also.

>> PS. UPPER CASE IS NOT COMPULSORY FOR cobol

But is is so ADDICTIVE...

Hein.

Re: How to define arguments for callable programs written in COBOL

John T. Farmer — Mon, 16 Oct 2006 08:14:42 GMT

Thanks to all that replied. JF