Joined: 26 Nov 2002 Posts: 12372 Topics: 75 Location: San Jose
Posted: Thu Jul 08, 2004 10:32 am Post subject: BPXWDYN Documentation
Code:
Introduction to BPXWDYN
BPXWDYN is a text interface to a subset of the SVC 99 (dynamic allocation) and SVC 109 (dynamic output) services. BPXWDYN supports data set allocation, unallocation, concatenation, and adding and deleting output descriptors.
The primary intent of this function is to make dynamic allocation and dynamic output services easily accessible by programs running outside of a TSO environment, however, this also functions in a TSO environment.
An output descriptor is associated with a SYSOUT allocation by using the OUTDES key on the SYSOUT allocation request or by creating a default output descriptor.
The syntax for allocation is quite similar to TSO for the TSO ALLOCATE and FREE commands. It should be possible to provide parameters to BPXWDYN that would be acceptable as a TSO ALLOCATE or FREE command. There are keys that TSO ALLOC supports that are not currently supported by BPXWDYN. There are also some keys that can be used with BPXWDYN that are not compatible with TSO.
The syntax for accessing dynamic output facilities is similar to the TSO OUTDES command, but identifying the name of the output descriptor is not the same.
BPXWDYN is an existing internal function within OpenEdition services. This document describes how to access it and use it. Some keywords listed in this document are not available at all levels of OpenEdition. A release level will be noted on those keys. A version of BPXWDYN is also available via FTP. This version supports all keywords. It is contained in an unloaded load library so it should be downloaded in binary format and copied to an MVS system into an FB 80 data set. It is restored using TSO/E RECEIVE:
receive inda(your.dataset.name)
It can replace BPXWDYN in SYS1.LINKLIB, be placed in a data set ahead of this in your linklist, or be loacated in your STEPLIB.
Calling Conventions
BPXWDYN is designed to be called from REXX, but may also be called by any program. Three parameter list forms are supported.
REXX External Function Parameter List
This parameter list allows REXX programs to call the BPXWDYN programs as a function or subroutine. They must be called with a single string parameter:
if BPXWDYN("alloc dd(sysin) da('my.dataset') shr")<>0 then
call allocfailed
Conventional MVS Variable Length Parameter String
This is the same parameter list as is generated by ADDRESS LINKMVS with one parameter and JCL with EXEC PGM=,PARM=. This parameter list form is simple to use by any program. Note that this is a single item variable length parameter list. The high bit is on in the parameter address word and length is a half word.
Null Terminated String Parameter
This parameter list is used most easily from C passing a string to BPXWDYN defined with a #pragma for OS linkage, or extern "OS" for C++. Note that the high bit is on in the parameter address word.
Request Types
The request is specified in a string parameter. The following request types are supported:
ALLOC
Dynamic allocation of a data set
FREE
Dynamic unallocation of a DD name or free an output descriptor
CONCAT
Dynamic concatenation of a DD name list
OUTDES
Create an output descriptor
The request type should be the first keyword in the parameter string. If a valid request type is not the first keyword, the request type defaults to ALLOC.
Keywords
The ordering of keywords on the request can be arbitrary.
Keys cannot be specified multiple times for one request.
BPXWDYN does no consistency checking on keys. If some keys are not valid together on a single request, dynamic allocation or dynamic output will fail the request.
Some keywords accept arguments. Keyword arguments must be specified within parenthesis. Spaces are not permitted between the key and the opening parenthesis or anywhere within the additional argument string through the closing parenthesis unless the argument string is quoted. Spaces are permitted between key specifications. Where multiple arguments are permitted, the arguments must be separated by commas.
An argument may be enclosed within quotes. Either single (') or double (") quotes may be used. Two adjacent quotes cannot be used to represent a single quote within a quoted string.
Arguments that are not quoted are treated as upper case. Arguments that are quoted are only treated as mixed case if it makes sense for the keyword.
Return Codes
When BPXWDYN is called as a REXX function or subroutine, the return code can be accessed in RESULT or as the value of the function. When called as a program, the return code is available in R15.
BPXWDYN returns the following codes:
0
Success
20
Invalid parameter list. See Calling Conventions for parameter list formats.
-21 to -9999
Key error
-100nn
Message processing error. IEFDB476 returned code nn.
>0
Dynamic allocation or dynamic output error codes
Understanding Key Errors
The low order two digits is the number of the key that failed the parse, offset by 20. The first key will have the value 21.
The high order two digits is a diagnostic code that indicates where in the code the parse failed. If the high digits are 0, the key itself was probably not recognized. Other values usually indicate a problem with the argument for the failing keyword. Likely causes are blanks in arguments that are not quoted and spelling of key names.
Understanding Dynamic Allocation Error Codes
The return code contains the dynamic allocation error reason code in the high two bytes and the information reason code in the low two bytes.
You can use the high four hex digits to lookup the error code in the dynamic allocation error reason codes table found in the Application Development Guide for Authorized ASM Programs.
Understanding Dynamic Output Error Codes
The return code contains the dynamic output return code in the high two bytes (S99ERROR) and the information code (S99INFO) in the low two bytes.
You can use the high four hex digits to lookup the error code in the dynamic output return codes table found in the Application Development Guide for Authorized ASM Programs and the low four digits to look up the information code.
There is no indication of the key that is in error.
Some of the most likely reason codes are:
300-30C,312,380
Make sure the arguments are specified correctly
401
The output descriptor already exists
402
The output descriptor does not exist
403
Output descriptors created by JCL cannot be deleted by dynamic output
Messages are not produced for dynamic output errors.
Message processing
Dynamic allocation provides message text for failed allocation requests. It is usually easier to use this message text rather than decode allocation return codes.
BPXWDYN can return these messages to a REXX program. By default the messages are returned in the S99MSG. stem. S99MSG.0 contains the number of messages and S99MSG.1, ... contains the message text.
The name of the stem can be changed by using the MSG key. A stem is not required. Digits are simply appended to the variable specified by the MSG key.
The MSG key can also be used to request allocation to issue the messages to your job log (write to programmer using WTO).
Under OpenMVS, messages can be written to opened files by providing the file descriptor number as the argument to MSG. MSG(2), for example, will write messages to the STDOUT file.
No support is provided to directly output messages to a user.
Using the Dynamic Allocation Request
To request dynamic allocation, specify alloc at the beginning of the parameter string.
BPXWDYN supports single data set allocation. Many of the common allocation keys can be used. Some additional keys are also supported to access additional functions.
The following keys are supported:
DD(DDname)
FI(DDname)
DDname to free or allocate
RTDDN(variable)
Return allocated DDname into the REXX variable variable. Available in OS390 R8
DA(data set name[(member name)])
DSN(data set name[(member name)])
Data set name to allocate. The name must be fully qualified and may include a member name. Quotes can be used for TSO compatability.
RTDSN(variable)
Return allocated data set name into the REXX variable variable. Available in OS390 R8
MOD
NEW
OLD
SHR
Specifies the data set status
CATALOG
DELETE
KEEP
UNCATALOG
Specifies the data set disposition
TRACKS
Space is to be allocated by tracks
CYL
Space is to be allocated by cylinders
BLOCK
Space is to be allocated by blocks Available in OS390 R10
DIR(directory blocks)
Number of directory blocks
SPACE(primary[,secondary])
Specifies primary and optionally secondary space allocations
VOL(volser [,volser...])
VOLSER specification. A list of volumes is available in R10
MAXVOL(num vols)
Number of volumes for a multi-volume data set. Available in R10
RTVOL(variable)
Return allocated volume name into the REXX variable variable. Available in OS390 R8
UNIT(unit name)
Specifies unit name, device type, or unit address
SYSOUT[(class)]
Specifies that a sysout data set is to be allocated and optionally defines the output class
SUBSYS(subsys name[,subsys parm]...)
Directs the allocation request to subsys name. with optional parameters. Case is preserved for quoted parms, otherwise the parm is upper-cased. Null parameters can also be specified by leaving a subsys parm empty. Availability not yet targeted for product
WRITER(external writer name)
Names the external writer
FORMS(forms name name)
Specifies the print form
DEST(destination)
Specifies the output destination
DEST(node[.user])
Specifies the output destination and node Available in OS390 R7
COPIES(number of copies)
Specifies the number of copies to print
DUMMY
Allocate a dummy data set
BLKSIZE(block size)
Specify the block size
LRECL(record length)
Specifies the logical record length
DSORG(PS|PO|DA)
Specifies the data set organization
RECFM(format[,format...])
Specifies the record format. The valid values are: A, B, D, F, M, S, T, U and V. Several may be used in combination.
BUFNO(number)
Set number of buffers. This number should be in the range 1-255. Numbers outside that range will give unpredictable results. Available in OS390 R9
OUTDES(output descriptor name)
Output descriptor name
STORCLAS(storage class)
Specifies the storage class
MGMTCLAS(management class)
Specifies the management class
DATACLAS(data class)
Specifies the data class
RECORG(LS)
Create a VSAM linear data set
DSNTYPE(LIBRARY|PDS|HFS)
Specifies the data set type
SPIN(UNALLOC)
Spin off a sysout data set at unallocation
MSG(WTP|default.S99MSG.|stemname|fdnum)
Direct allocation messages to your job log (WTP), a REXX stem, or a file identified by a file descriptor number. If this key is not specified, messages will be returned in the S99MSG. stem, if possible. If the program was not called by a REXX exec, the messages will be lost.
NORECALL
Fail the allocation request if the data set is migrated
PATH(pathname)
Pathname to allocate.
PATHOPTS(path options list)
Set options for pathname allocation. This list is a list of keywords separated with commas. The supported keywords are: ORDWR OEXCL OSYNC OTRUNC OCREAT OWRONLY ORDONLY OAPPEND ONOCTTY ONONBLOCK.
PATHMODE(path mode list)
Set mode bits for a new allocation. This list is a list of keywords separated with commas. The supported keywords are: SIRUSR SIWUSR SIXUSR SIRWXU SIRGRP SIWGRP SIXGRP SIRWXG SIROTH SIWOTH SIXOTH SIRWXO SISUID SISGID SISVTX.
PATHPERM(octal path mode)
Set mode bits for a new allocation. This key is effectively the same as PATHMODE but accepts a simple octal number for the mode bit settings.
PATHDISP(KEEP|DELETE[,KEEP|DELETE])
Specifies file disposition for normal and abnormal termination of the job step. Available in OS390 R3
FILEDATA(TEXT|BINARY)
Tells the sequential access method services whether the data is to be treated as text or binary. Available in OS390 R5
REUSE
Causes the named DD to be freed before the function is performed. Available in OS390 R5
SHORTRC
If the dynamic allocation fails, the dynamic allocation error code (S99ERROR) is returned in R15 and the information code is not returned. This is useful is the application can only process R15 as a half word, such as PL/I. Available in OS390 R6
Using the FREE Request for Dynamic Unallocation
To request dynamic unallocation, specify free at the beginning of the parameter string.
BPXWDYN supports single data set unallocation. Most common unallocation keys can be used. The following keys are supported:
DD(DDname)
FI(DDname)
DDname to free
DA(data set name[(member name)])
DSN(data set name[(member name)])
Data set name to free. The name must be fully qualified and may include a member name. Quotes are optional.
CATALOG
DELETE
KEEP
UNCATALOG
Overrides the disposition
SYSOUT(class)
Overrides the output class
SPIN(UNALLOC)
Spin off the sysout data set at unallocation
MSG(WTP|default.S99MSG.|stemname|fdnum)
Direct allocation messages to your job log (WTP), a REXX stem, or a file identified by a file descriptor number. If this key is not specified, messages will be returned in the S99MSG. stem, if possible. If the BPXWDYN was not called by a REXX exec, the messages cannot be returned in a stem. WTP should be specified to obtain messages.
SHORTRC
If the dynamic allocation fails, the dynamic allocation error code (S99ERROR) is returned in R15 and the information code is not returned. This is useful is the application can only process R15 as a half word, such as PL/I. Available in OS390 R6
Using the Dynamic Concatenation Request
To request dynamic concatenation, specify concat at the beginning of the parameter string.
This function concatenates multiple DDs to a single DD. The DDs are concatenated in the order specified in the DDLIST key. The following keys are supported:
CONCAT
Command verb to concatenate data sets identified by DD names If no command verb is specified, ALLOC is assumed.
DDLIST(DDname1,DDname2[,DDnamex...] )
Specify a list of DD names to concatenate to DDname1. This key should be used with the CONCAT key.
MSG(WTP|default.S99MSG.|stemname|fdnum)
Direct allocation messages to your job log (WTP), a REXX stem, or a file identified by a file descriptor number. If this key is not specified, messages will be returned in the S99MSG. stem, if possible. If the program was not called by a REXX exec, the messages will be lost.
SHORTRC
If the dynamic allocation fails, the dynamic allocation error code (S99ERROR) is returned in R15 and the information code is not returned. This is useful is the application can only process R15 as a half word, such as PL/I. Available in OS390 R6
Using the Dynamic Output Request
To request dynamic output, specify outdes at the beginning of the parameter string. This keyword takes an argument that names the output descriptor. The keyword is described below.
The following keys are supported:
OUTDES(descriptor name)
Names the output descriptor to be added. This must be the first key specified in the parameter string.
ADDRESS(address[,address...])
Specifies the delivery address. Dynamic output will allow up to four arguments to be specified.
BUILDING(building)
Specifies the building location
BURST
Directs output to a stacker
CHARS(chars[,chars...])
Names the character arrangement tables.
CLASS(class)
Assigns the SYSOUT class.
CONTROL(spacing)
Specifies line spacing or that the records begin with carriage control characters. The valid values are:
Single
Single spacing
Double
Double spacing
Triple
Triple spacing
Program
Records begin with carriage control characters
COPIES(number of copies)
Specifies the number of copies to be printed.
DEFAULT
Specifies that this is a default output descriptor.
DEPT(department)
Specifies the department identification.
DEST(node[.user])
Send the SYSOUT to the specified destination.
DPAGELBL
Specifies that a security label be placed on the output.
FCB(fcb name)
Specifies the FCB image.
FLASH
Specifies the forms overlay.
FORMDEF(formdef name)
Names the formdef.
FORMS(forms name)
Names the forms to print on.
MODIFY(trc number)
Specifies which character arrangement table is to be used.
NAME(owner name)
Specifies the owner's name.
NOTIFY([node.]user)
Sends print completion message to the destination.
Using the FREE Request to Free an Output Descriptor
To request that an output descriptor be freed, specify free at the beginning of the parameter string.
kolusu,
I want to dynamically allocate files from my cobol program. I tried the following and its working -
MOVE 'FFF2414.DYN2' TO FILENAME.
STRING 'ALLOC DD(O) DSN(' QUOTE FILENAME QUOTE ') NEW '
' TRACKS SPACE(01,01) CATALOG'
' STORCLAS(STANDARD) MGMTCLAS(WORK) '
' LRECL(400) RECFM(F,B) BLKSIZE(4000)'
DELIMITED BY SIZE
INTO WS-ALLOC-STRING
END-STRING.
DISPLAY ' WS-ALLOC-STRING *' WS-ALLOC-STRING '*'
CALL 'BPXWDYN' USING WS-ALLOC-STRING.
But I want to allocate the file on TAPE. I tried with UNIT(TAPE) But it is not working. Can you plz help?
Joined: 26 Nov 2002 Posts: 12372 Topics: 75 Location: San Jose
Posted: Mon Jul 19, 2004 3:34 pm Post subject:
Shail,
The allocation on tape depends on the unit names defined in your system. Every shop has their own standard of naming the tape devices. Our shop has named uses unit=cart, which is used to allocate datasets on tapes. So check with your systems people about the tape device names
The device name is TAPE only (UNIT=TAPE). That is what we use in JCLs. I am not sure if I am using the correct syntax. Also plz tell if this is possible or not. Can there be any access issues? Below is what I tried with-
Code:
MOVE 'FFF2414.DYN2' TO FILENAME.
STRING 'ALLOC DD(O) DSN(' QUOTE FILENAME QUOTE ') NEW '
'UNIT(TAPE) CATALOG'
' STORCLAS(STANDARD) MGMTCLAS(WORK) '
' LRECL(400) RECFM(F,B) BLKSIZE(4000)'
DELIMITED BY SIZE
INTO WS-ALLOC-STRING
END-STRING.
DISPLAY ' WS-ALLOC-STRING *' WS-ALLOC-STRING '*'
CALL 'BPXWDYN' USING WS-ALLOC-STRING.
Joined: 03 Jan 2003 Posts: 1014 Topics: 13 Location: Atlantis
Posted: Tue Jul 20, 2004 12:26 am Post subject:
BPXWDYN is an interface to SVC 99 (sometimes called DYNALLOC). SVC99 returns reason codes that will tell you exactly what 'text unit' failed. You may need to refer to the SVC99 documentation to figure out what the numbers mean. If you've never coded an SVC 99 in assembler, it may not make too much sense at first, but look at it a couple of times and it should start to make sense. If the program runs under TSO, I'd also suggest using the MSG(WTP) verb so you can see the error messages at your terminal.
It is probably easiest to prototype the call in Rexx since, if I read the doc above correctly, that provides several means to see the messages, but it may not mirror the final environment you plan to run in.
(personally, my ids have never had the authority to allocate a tape)
Hi Kolusu,
Had a question here. If we are allocation a dataset thru BPXWDYN can we reserve it so that no other task can reference the dataset for the period of use.
Like if we give a DISP=OLD in the JCL and if any other job tries to access the DS it goes in wait until the resource is used.
Hi,
My requirement is that I need to delete datasets dynamically. Now while deletion I need to ensure that the datasets are not in use by anyone else.
If the datasets are in use then I need to queue the request and wait until the dataset becomes free (i.e the program should not fail if the dataset is in use by someone else).
So is there a way we can tell BPXWDYN to queue the request??
Joined: 03 Jan 2003 Posts: 1014 Topics: 13 Location: Atlantis
Posted: Thu May 25, 2006 11:30 pm Post subject:
I doubt it. That is the function of the system ENQ, but if I recall, you can't do an ENQ on the SYSDSN major name unles your code runs authorized. If your initial allocation fails, you could submit an IEFBR14 job with a ddname using DISP=(OLD, DELETE,DELETE) for each remaining data set, but that would waste an initiator, potentially for a very long time (and you aren't gaurenteed to run immediately anyway). If you do this all in 1 job and maybe have a dedicated job class for it it might be an OK solution. It depends on the system setup and use. or you coild go into a sleep loop (yuck).
Hi,
I need to do this through a program, (PL/1). I can't use JCL's for this purpose.
The only way I see is either we add a loop and loop until the dataset becomes free (but this will not gurantee that we get a hold because someone else might creep in) or use DYNALLOC and set the Reserve request bit on so that it gets queued to major name SYSDSN and ensures that we will get a hold on the dataset.
You cannot post new topics in this forum You cannot reply to topics in this forum You cannot edit your posts in this forum You cannot delete your posts in this forum You cannot vote in polls in this forum
FAQ
Search
Quick Manuals
Register
Profile
Log in to check your private messages
Log in
