How to define arguments for callable programs written in COBOL

[John T. Farmer]

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

[Hein van den Heuvel]

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.

[John T. Farmer]

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

[Richard J Maher]

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

[comarow]

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.

[John T. Farmer]

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

Thanks,

John

[comarow]

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.

[Jan van den Ende]

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

[comarow]

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

[Richard J Maher]

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

[John T. Farmer]

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

[John T. Farmer]

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

[Hein van den Heuvel]

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.

[John T. Farmer]

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

[Hein van den Heuvel]

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.

[John T. Farmer]

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

[Jan van den Ende]

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

[Richard J Maher]

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

[Hein van den Heuvel]

>> 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.

[John T. Farmer]

Thanks to all that replied. JF