Calling BPXWDYN to Return DSNAME for DDNAME

[David Staudacher]

Someone in a LinkedIn group I manage recommended calling BPXWDYN (obfuscated SVC 99) as a solution for retrieving allocation information (see linkd.in/2CRCw87 ).
Looking into it, I found some tantalizing references, but *everything* I could find was either inaccurate or misleading.
So, by trial and error, I worked up the following simple example of how to obtain the DSNAME for a given DDNAME by calling BPXWDYN in Assembler:
GETDSN AMODE 31
GETDSN RMODE ANY
GETDSN CSECT
SAVE (14,12) SAVE CALLER REGS
LR 12,15 R12 = BASE
USING GETDSN,12
LA 1,RSA R1 -> NEW REG SAVE AREA
ST 13,4(,1) CHAIN BACK
LR 13,1 R13 -> RSA
LOAD EP=BPXWDYN
LR 15,0 R15 -> BPXWDYN
SR 0,0 R0 = 0
CALL (15),(INFODD,INRTDSN),VL
L 13,4(,13) R13 -> OLD REG SAVE AREA
RETURN (14,12),RC=(15)
INFODD DC C'INFO DD(DDNAME)',X'00'
INRTDSN DC AL2(45),C'INRTDSN',XL38'00'
RSA DS 18F

Setting R0 = 0 is essential!

Sample JCL for use with above:
/ EXEC PGM=GETDSN
//DDNAME DD DISP=SHR,DSN=<dsname>

On return, the allocated DSN is returned at INRTDSN+2, with the halfword length at INRTDSN+0.
Documentation (such as there is) for calling BPXDYN is found here:
http://publibfp.boulder.ibm.com/cgi-bin/bookmgr/BOOKS/bpxzb6a0/6.0 - "BPXWDYN: a Text Interface to Dynamic Allocation and Dynamic Output"
http://publibfp.boulder.ibm.com/cgi-bin/bookmgr/BOOKS/bpxzb6a0/6.9 - "Requesting Allocation Information"
But the only actual example of information retrieval is in REXX:
http://publibfp.boulder.ibm.com/cgi-bin/bookmgr/BOOKS/bpxzb6a0/6.12 - "Examples: Calling BPXWDYN From a REXX Program"

I'm quite familiar with how to do this using SVC 99 and would prefer to, given the excellent documentation for it:
http://publibfp.boulder.ibm.com/cgi-bin/bookmgr/BOOKS/IEA2A8C1/25.0 - "Dynamic Allocation"
http://publibfp.boulder.ibm.com/cgi-bin/bookmgr/BOOKS/IEA2A8C1/26.0 - "Requesting Dynamic Allocation Functions"
... but thought I'd publish this as it's the only clear example I know of anywhere showing how to call BPXWDYN from Assembler for information retrieval.

[David Staudacher]

LinkedIn discussion at http://linkd.in/2CRCw87 (adds "http://" prefix to generate clickable link ).

[David Staudacher]

"Setting R0 = 0 is essential!" Unless you have this APAR fix installed:
http://ibm.com/support/docview.wss?uid=isg1OA51807 - "OA51807: NEW FUNCTION - BPXWDYN ALTERNATE ENTRY POINT BPXWDY2 FOR HIGH LEVEL LANGUAGE PROGRAM CALLERS"
Then you can call BPXWDY2 instead of BPXWDYN.

[Paul Gilmartin]

On 2017-12-22, at 06:35:14, David Staudacher wrote:

> Someone in a LinkedIn group I manage recommended calling BPXWDYN (obfuscated SVC 99) as a solution for retrieving allocation information (see linkd.in/2CRCw87 ).
> Looking into it, I found some tantalizing references, but *everything* I could find was either inaccurate or misleading.

> So, by trial and error, ...
>
This seems to be well covered in:
z/OS Using REXX and z/OS UNIX System
Services
Version 2 Release 3
Conventional MVS parameter list

... which your example code matches. What deficiencies do you see?
For whatever they are, you should submit a RCF.

In Rexx I've found BPXWDYN most valuable for:
o RTDDN to avoid DDNAME collisions
o RTDSN and RTVOL to reallocate temp DSNs to different DDNAMEs.
Alas, these seem not to work for VIO.

-- gil

[Willy Jensen]

Seems that BPXWDYN will accept 2 types of call from ASM:

With a length field at the front like.
alc1 dc y(alc1l),c'alloc dd(mydd1) dsn(WJ.TEST.DS1) shr'
alc1l equ *-alc1-2

Null-delimited like:
alc2 dc y(alc1l),c'alloc dd(mydd2) dsn(WJ.TEST.DS2) shr',x'00'

both
Link EP=BPXWDYN,param=alc1,VL=1
and
Link EP=BPXWDYN,param=alc2,VL=1
allocates the dataset named.

But for returning a value the version with a length at front must be used like
inrtdsn dc y(44),cl44'INRTDSN'

Willy

[Farley, Peter x23353]

That is terrific news! Thank you!

Peter

This message and any attachments are intended only for the use of the addressee and may contain information that is privileged and confidential. If the reader of the message is not the intended recipient or an authorized representative of the intended recipient, you are hereby notified that any dissemination of this communication is strictly prohibited. If you have received this communication in error, please notify us immediately by e-mail and delete the message and any attachments from your system.

[David Staudacher]

Ref: z/OS Using REXX and z/OS UNIX System Services Version 2 Release 3 "Conventional MVS parameter list"

"What deficiencies do you see?"

http://www.ibm.com/support/knowledgecenter/SSLTBW_2.3.0/com.ibm.zos.v2r3.bpxb600/retparml.htm
... was indeed one of the better ones I found, but there are still many inaccuracies. It stays, for example, "The parm string has the format of either halfword length followed by the parameter string or a null-terminated parameter string. My findings, using a z/OS 1.13 system, were that the "halfword length followed by the parameter string" format doesn't work. The "parm string" *must be* null terminated with no halfword length prefix. I doubt that's changed even in the latest z/OS. Nor does it clearly describe exactly what the correct "parm string" is for DSNAME information retrieval. The manual mentions 6 "request types": ALLOC, CONCAT, DECONCAT, FREE, INFO and OUTDES. Only by trial and error was I able to figure out that the correct parm string is "INFO DD(<ddname>)". The manual calls DD a "keyword" for information retrieval and the diagram you reference shows keywords coming *after* the parm string, yet the DD "keyword" is in fact a necessary part of the parm string itself.
Also, the keyword used for DSNAME retrieval in all the examples is "RTDSN", which you also mention, but in the manual under "Requesting Allocation Information":
https://www.ibm.com/support/knowledgecenter/SSLTBW_2.3.0/com.ibm.zos.v2r3.bpxb600/bpx1rx78.htm
... it says "INRTDSN", which is in fact the one that works - not "RTDSN".

I've never submitted an RCF (not even sure what it is). How does one do that?

[Paul Gilmartin]

On 2017-12-22, at 10:23:34, Willy Jensen wrote:
> ...

> But for returning a value the version with a length at front must be used like
> inrtdsn dc y(44),cl44'INRTDSN'
>

Mmmm... I see:

z/OS Using REXX and z/OS UNIX System
Services
Version 2 Release 3
Conventional MVS parameter list

... The length is set to the length of the data returned excluding the
terminating null.

If a keyword value is not returned, a null string is returned.

Guideline: Because a null-terminated string is returned, in order to ensure that the
data is returned, the parameter area must be large enough for the expected
returned data plus the null character.

So should it be 45 instead of 44?

-- gil

[Paul Gilmartin]

This might merit both SR and RCF. But supply concrete examples of
the misbehavior.

> I've never submitted an RCF (not even sure what it is). How does one do that?
>

Can't find it from your web link. But from the PDF:

z/OS Using REXX and z/OS UNIX System Services
Version 2 Release 3

How to send your comments to IBM

We appreciate your input on this documentation. Please provide us with any
feedback that you have, including comments on the clarity, accuracy, or
completeness of the information.
Use one of the following methods to send your comments:
Important: If your comment regards a technical problem,
see instead “If you have a technical problem.”
v Send an email to mhv...@us.ibm.com. v Send an email from the Contact z/OS
web page (www.ibm.com/systems/z/os/zos/webqs.html).
(More instructions trimmed.)

-- gil

[Willy Jensen]

Oops, just spotted an error with alc2 in my mail.
But null-delimited string like this works too:

Link EP=BPXWDYN,param=alc2,VL=1
. . .
alc2 dc c'alloc dd(mydd2) dsn(WJ.TEST.DS2) shr',x'00'

-----Oprindelig meddelelse-----
Fra: IBM Mainframe Assembler List [mailto:ASSEMBL...@LISTSERV.UGA.EDU] På vegne af Willy Jensen
Sendt: 22. december 2017 18:24
Til: ASSEMBL...@LISTSERV.UGA.EDU
Emne: SV: Calling BPXWDYN to Return DSNAME for DDNAME

[Willy Jensen]

'My findings, using a z/OS 1.13 system, were that the "halfword length followed by the parameter string" format doesn't work. The "parm string" *must be* null terminated with no halfword length prefix'

I have tested both versions in 1.13 and 2.3 systems successfully.

[David Staudacher]

"I have tested both versions in 1.13 and 2.3 systems successfully."

Good to know Willie! Could you post the essentials of your successful INFO call to return DSNAME for DDNAME?
I'd like to see how it differs from mine, which failed.

[Willy Jensen]

Sure, here is an extract from my program, the relevant JCL, plus an output sample. MAKESTR is a macro of mine to format a string, The LOG macro is basically a PUT SYSPRINT.

LOAD EP=BPXWDYN
lr r10,0

* length at front
lr 15,10 r15 -> bpxwdyn
sr 0,0 r0 = 0
call (15),(info1,inrtds1),VL
st r15,fw
makestr logr,'rc ',(fw,4,cvxd), c
' dsn: ',(inrtds1,2,cvxd),+1,(inrtds1+2,44)
log ,

* null-delimited
lr 15,10 r15 -> bpxwdyn
sr 0,0 r0 = 0
call (15),(info2,inrtds2),VL
st r15,fw
makestr logr,'rc ',(fw,4,cvxd), c
' dsn: ',(inrtds2,2,cvxd),+1,(inrtds2+2,44)
log ,

DELETE EP=BPXWDYN

INFO1 dc y(info1l),C'INFO DD(INFOLIB1)'
info1l equ *-info1-2
inrtds1 dc y(44),cl44'INRTDSN'

INFO2 dc C'INFO DD(INFOLIB2)',x'00'
inrtds2 dc y(44),cl44'INRTDSN'

//G.SYSPRINT DD SYSOUT=*
//G.INFOLIB1 DD DISP=SHR,DSN=WJENSEN.LIB.CLIST
//G.INFOLIB2 DD DISP=SHR,DSN=WJENSEN.LIB.CNTL

rc 00000000 dsn: 0011 WJENSEN.LIB.CLIST
rc 00000000 dsn: 0010 WJENSEN.LIB.CNTL

-----Oprindelig meddelelse-----
Fra: IBM Mainframe Assembler List [mailto:ASSEMBL...@LISTSERV.UGA.EDU] På vegne af David Staudacher
Sendt: 23. december 2017 21:22
Til: ASSEMBL...@LISTSERV.UGA.EDU
Emne: Re: Calling BPXWDYN to Return DSNAME for DDNAME

[David Staudacher]

>> "I have tested both versions in 1.13 and 2.3 systems successfully."
> Good to know Willie! Could you post the essentials of your successful INFO call to return DSNAME for DDNAME?
> I'd like to see how it differs from mine, which failed.

Willie:
Here are the essentials of my version which works.
The request parm *does not* have a halfword length prefix:
CALL BPXWDYN,(INFODD,INRTDSN),VL
[...]

INFODD DC C'INFO DD(DDNAME)',X'00'
INRTDSN DC AL2(45),C'INRTDSN',XL38'00'

And here is the version which fails with a S0C4.
The request parm *does* have a halfword length prefix:

CALL BPXWDYN,(INFODD,INRTDSN),VL
[...]
INFODD DC CALL BPXWDYN,(INFODD,INRTDSN),VL
[...]
INFODD DC AL2(16),C'INFO DD(DDNAME)',X'00'

INRTDSN DC AL2(45),C'INRTDSN',XL38'00'

The manual says the above should work, but it doesn't.
Could you post the essentials of your successful INFO call using a request parm with a halfword lenth prefix?
I'd like to see how it differs from mine.

[Paul Gilmartin]

On 2017-12-24, at 04:51:16, Willy Jensen wrote:
>
> INFO1 dc y(info1l),C'INFO DD(INFOLIB1)'
> info1l equ *-info1-2
> inrtds1 dc y(44),cl44'INRTDSN'
>
> INFO2 dc C'INFO DD(INFOLIB2)',x'00'
> inrtds2 dc y(44),cl44'INRTDSN'
>

inrtds2 is not null-delimited as it was in David's example.

According to the Ref. manual, you *always* need a byte for the
returned trailing null. Have you inspected the character after
the returned DSN or tried with a 44-character DSN?

z/OS IBM Using REXX and z/OS UNIX System Services

Version 2 Release 3

Conventional MVS parameter list

...
Upon return, the return areas will contain a null-terminated string
for the field requested if it was available and if it fits into
the area. A null string is returned if the data does not fit into
the parameter area. The length is set to the length of the data

returned excluding the terminating null.

If a keyword value is not returned, a null string is returned.

Guideline: Because a null-terminated string is returned, in order
to ensure that the data is returned, the parameter area must be
large enough for the expected returned data plus the null character.

The C example in this section has lengths of 9 and 45:
RTARG ddname = {9,"rtddn"};
RTARG dsname = {45,"rtdsn"}

The Ref. seems to lack an example of calling with returned variables
and a null-terminated parameer string.

-- gil

[Paul Gilmartin]

A difference I see is that David counted a trailing null:

On 2017-12-24, at 04:51:43, David Staudacher wrote:
> INFODD DC AL2(16),C'INFO DD(DDNAME)',X'00'

....+....|....+.

Willy did not count it:

On 2017-12-24, at 04:51:16, Willy Jensen wrote:
> INFO1 dc y(info1l),C'INFO DD(INFOLIB1)'
> info1l equ *-info1-2

-- gil

[retired mainframer]

The length of the request is 15 characters, not 16. You have told BPXWDYN that the X'00' is part of the request.

[David Staudacher]

"The length of the request is 15 characters, not 16. You have told BPXWDYN that the X'00' is part of the request."

From what I gather reading the reference Paul Gilmartin posted, the null-terminator byte should be included in the length:

http://www.ibm.com/support/knowledgecenter/SSLTBW_2.3.0/com.ibm.zos.v2r3.bpxb600/retparml.htm

Note: {45,"rtdsn"} for the DSNAME request return area, while max DSNAME length is 44.

[Willy Jensen]

Gil you are right, there should be room for a trailing null in the return string. In my sample it did not matter as the length of the returned value was less than 44. A dump of the returned string shows a x'00' immediately after the datasetname.
The manual says 'The keyword must end with a blank or null character', so

INRTDSN DC AL2(45),C'INRTDSN',XL38'00'

and
INRTDS2 DC Y(45),CL45'INRTDSN'
are both ok.

As to the request, I found that even including a trailing null did not matter, so this worked:
INFO1 DC Y(INFO1L),C'INFO DD(INFOLIB1)',X'00'
INFO1L EQU *-INFO1-2
This, however, failed:
INFO1 DC Y(INFO1L),C'INFO DD(INFOLIB1)',X'FF'
INFO1L EQU *-INFO1-2
But with an error code x' FFFFFFE9', not an abend.

The length field of course must match the length of the string.

Willy