2012年5月18日 星期五

BPXWDYN Documentation


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.


Figure 1.


 
      *-*------------------*
 R1-->|1| parm string addr *---*
      *-*------------------*   |
       *-----------------------*
       |     *-------*---------------------*
       *---->| length| parameter string    |
             *---*---*---------------------*
 




PL/I usage might include the following statements:

  DCL PLIRETV BUILTIN;
  DCL BPXWDYN EXTERNAL ENTRY OPTIONS(ASM INTER RETCODE);
  DCL ALLOC_STR CHAR(100) VAR
        INIT('ALLOC FI(SYSIN) DA(MY.DATASET) SHR');
  FETCH BPXWDYN;
  CALL BPXWDYN(ALLOC_STR);


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.


Figure 2.


 
      *-*------------------*
 R1-->|1| parm string addr *---*
      *-*------------------*   |
       *-----------------------*
       |     *----------------------*---*
       *---->|  parameter string    |00x|
             *----------------------*---*
 




C usage might include the following statements:

  typedef int EXTF();
  #pragma linkage(EXTF,OS)
  EXTF *bpxwdyn;
  int  rc;
  bpxwdyn=(EXTF *)fetch("BPXWDYN");
  rc=bpxwdyn("alloc fi(sysin) da(my.dataset) shr");


--------------------------------------------------------------------------------

General Usage

--------------------------------------------------------------------------------

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.


OUTDISP(disposition)

Specifies the data set disposition.


PAGEDEF(pagedef name)

Names the pagedef.


PRMODE(print mode)

Identifies the process mode (LINE or PAGE).


ROOM(room identification)

Specifies the room identification.


TITLE(separator title)

Specifies the separator page title.


TRC

Specifies that the data set contains TRC codes.


UCS(UCS name)

Names the UCS or character arrangement table.


WRITER(external writer name)

Names an external writer to process the data set.


--------------------------------------------------------------------------------

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.

Only one keyword is supported


OUTDES(descriptor name)

Names the output descriptor to be freed.


--------------------------------------------------------------------------------

Examples

--------------------------------------------------------------------------------

Examples Calling BPXWDYN from REXX

Allocate SYS1.MACLIB to SYSLIB directing messages to OpenMVS stderr
 
    call bpxwdyn "alloc fi(syslib) da(sys1.maclib) shr msg(2)"


Free SYSLIB and trap messages in stem S99MSG.
 
    call bpxwdyn "free fi(syslib)"


Concatenate SYS1.SBPXEXEC to SYSPROC
 
    if bpxwdyn("alloc fi(tmp) da(sys1.sbpxexec) shr msg(2)")=0 then
       call bpxwdyn "concat ddlist(sysproc,tmp) msg(2)"


Create descriptor P20 with distribution information
 
   call bpxwdyn "outdes(p20) dest(kgn.p20n10)",
               "address('WJ Schoen','M/S 619')",
               "name(wschoen) bin(0004) dept(64ba)"


Free descriptor P20
 
   call bpxwdyn "free outdes(p20)"


--------------------------------------------------------------------------------

Examples Calling BPXWDYN from C

Free descriptor P20

Allocate SYS1.MACLIB to SYSLIB directing messages to OpenMVS stderr
 
   typedef int EXTF();
   #pragma linkage(EXTF,OS)
 
   int call_alloc()
   {
   EXTF *bpxwdyn=(EXTF *)fetch("BPXWDYN");
   return bpxwdyn("alloc fi(syslib) da(sys1.maclib) shr msg(2)")
   }

沒有留言:

張貼留言