ALLOCATE Command

Syntax:

ALLOCATE keywords

Keywords:

ACCODE(code)

specifies the accessibility code for an ANSI tape data set. Code may contain 1 to 8 characters (only the first character is validated).

AVBLOCK(length)

specifies the average byte length of the data sets records. This keyword is used with the SPACE keyword to determine how much space is to be set aside for the data set.

AVGREC(unit-type)

used with the AVBLOCK and SPACE keywords to determine the quantity and increment values. Unit-types are:

U: byte units
K: 1024 byte units
M: 1,048,576 byte units

BFALN(alignment-type)

specifies buffer alignment. Alignment-types are:

F: fullword boundary
D: doubleword boundary

BFTEK(buffering-technique)

specifies the type of buffering. Buffering-techniques are:

S: simple
E: exchange
A: automatic record area
R: record

BLKSIZE(blocksize)

specifies the data set's DCB (data control block) block size. The number must be between 0 and 32,760. If you do not specify BLKSIZE and SMS is active, a block size will be selected for you. Also the model data set given on the LIKE keyword can determine block size.

BLOCK(length)

specifies the average block length of blocks written to the data set. This value is used with the SPACE keyword to determine how much space to allocate for the data set. length can range from 1 to 65,535.

BUFL(length)

specifies the length of buffers in the buffer pool. Length (in bytes) ranges from 1 to 32,760.

BUFNO(number)

specifies the number of DCB buffers. The number ranges from 1 to 255.

BUFOFF(prefix-length)

specifies the block prefix length. If you code L, the prefix is 4 bytes that contain the length of the block. You can also code a specific numeric prefix-length (range: 1 to 99).

BURST

specifies that the burster-trimmer-stacker on a 3800 printer is to be used. See NOBURST.

CATALOG

specifies that the data set is to be cataloged after it is freed. See KEEP, DELETE, and UNCATALOG.

CHARS(tablename-list)

specifies character arrangement table names for printing the data set on a 3800 printer. You may specify 1 to 4 table names. Each name can be 1 to 4 bytes long. This keyword is used with the SYSOUT keyword.

COPIES(nnn[,group-value...])

specifies the number of copies of the data set to be printed (nnn). You may also specify 1 to 8 group values that determine how the copies are to be grouped. This keyword is used with the SYSOUT keyword. You may not use the DATASET keyword with COPIES.

CYLINDERS

specifies that the unit of space is to be cylinders. This keyword is used with the SPACE keyword to determine how much space to set aside for the data set.

DATACLAS(class-name)

specifies the SMS data class name for the data set. This name can be 1-8 characters long. Data class determines important data set attributes such as RECFM, LRECL, RECORG, etc. SMS must be active for this keyword to be honored.

DATASET({dsname | dsname-list | *})

specifies the data set or list of data sets to be allocated. If an asterisk (*) is coded, the terminal is allocated. A fully qualified data set name is enclosed in single quotes. If you omit the quotes, the current userid will be appended to the front. Member names and generation numbers must be enclosed in parentheses. DSNAME is an alias for this keyword.

DDNAME(name)

specifies the 1 to 8 character name that your program will use to access the data set(s). If you do not specify this keyword the system generates a ddname for you (See S99DDN below). FILE is an alias for this keyword.

DELETE

specifies that the data set is to be deleted after it is freed. See KEEP, CATALOG, and UNCATLOG keywords.

DEN(density-code)

specifies the density of a magnetic tape. The valid values are:

0: 7 track, 200 bytes per inch (bpi)
1: 7 track, 556 bpi
2: 7 or 9 track, 800 bpi
3: 9 track, 1600 bpi
4: 9 track, 6250 bpi

DEST(dest[.userid])

dest specifies the remote location to which a SYSOUT data set is to be routed when the data set is freed. The optional userid specifies the specific user at the remote location that is to receive the data set.

DIAGNS(TRACE)

specifies a module trace of Open/Close/EOV work area and your DCB.

Note: This keyword must be coded exactly as shown.

DIR(integer)

specifies the number of directory blocks to be allocated for a partitioned data set. This number indirectly determines how many members the data set can have. If DIR is coded, a DSORG of PO (partitioned organization) is assumed.

DSNAME({dsname | dsname-list | *})

See DATASET keyword.

DSNTYPE({LIBRARY | PDS})

specifies the type of partitioned data set to be allocated. LIBRARY indicates a partitioned data set extended (PDSE). PDS indicates a standard partitioned data set.

DSORG(type)

specifies the data set organization. The following values may be coded:

DA: direct access
DAU: direct access unmovable
PO: partitioned organization
POU: partitioned organization unmovable
PS: physical sequential
PSU: physical sequential unmovable

If you do not specify DSORG, but you do specify DIR, a DSORG of PO is assumed. If you specify neither DSORG nor DIR, a DSORG of PS is assumed.

DUMMY

specifies that a dummy data set is to be allocated.

EROPT({ACC | SKP | ABE})

specifies error handling for record read/write errors. ACC indicates the block in error is to be accepted. SKP indicates the block in error is to be skipped. ABE indicates that the task is to be abended.

EXPDT({yyddd | yyyy/ddd})

specifies the data set expiration date. yy is the 2-digit year, yyyy is the 4-digit year, and ddd is the day of the year. See the RETPD keyword. Either this keyword or RETPD can be used, but not both.

Note: Two special values indicate permanent retention. These are 99365 and 1999/365.

FCB(image-id{,VERIFY | ,ALIGN})

specifies the 1 to 4 character forms control buffer image identifier. VERIFY indicates that the operator is to visually verify that image displayed is correct. ALIGN instructs the operator to check forms alignment.

FILE(name)

See DDNAME keyword.

FLASH(overlay-name[,copies])

specifies a forms overlay for a 3800 printer. Copies specifies the number of copies on which the overlay is to be printed. This keyword is used with the SYSOUT keyword.

FORMS(name)

specifies the 1 to 4 character name of the form on which the SYSOUT data set is to be printed.

HOLD

specifies that the SYSOUT data set is to be placed on the HOLD queue when the data set is freed. See NOHOLD.

INPUT

specifies input processing for BSAM and BDAM data sets.

KEEP

specifies that the data set is to be kept by the system after it is freed. See DELETE, CATALOG, and UNCATALOG keywords.

KEYLEN(length)

specifies the length of the keys used to locate blocks of records for DASD data sets. The length value ranges from 1 to 255.

KEYOFF(offset)

specifies for VSAM KSDS data sets the offset of the key in each record. This keyword is honored only if SMS is active.

LABEL(type)

specifies the type of label processing. The valid types are:

NL: no label.
SL: standard label.
NSL: non-standard label.
SUL: standard and a user label.
BLP: label processing to be bypassed.
LTM: leading tape mark (DOS unlabeled tape).
AL: American National Standard label.
AUL: American National Standard label and American National Standard user label.

LIKE(model-dsname)

specifies the name of an existing data set, the attributes of which are to be used in allocating the data set given in the DATA SET keyword. You may override specific attributes (such as BLKSIZE) simply by coding the attribute's keyword. This keyword cannot be used with the REFDD keyword. However, the DATA SET and NEW keywords must be specified.

Note: The operation of this keyword varies depending on whether SMS is active or not. If SMS is not active, some attributes may not be copied.

LIMCT(number)

specifies the number of blocks (or tracks) to search. The number ranges from 1 to 32,760.

LRECL({length | nnnnnK | X})

specifies the logical record length. The nnnnnK format specifies the LRECL in 1024 bytes. The X format is used for variable blocked data sets where the LRECL exceeds 32,756.

MAXVOL(count)

specifies the maximum number of volumes for a data set. The number can be 1 to 255.

MGMTCLAS(class-name)

specifies the SMS management class of the data set. The name can be 1-8 characters long. Management class determines how HSM handles data set migration and how often backups are taken. SMS must be active for this keyword to be honored.

MOD

specifies that data is to be added to the end of the data set, if it exists.

MODIFY(module[,trc])

specifies a copy modification module name for a 3800 printer. Trc specifies which CHARS keyword character arrangement table to use. The valid values for trc are 0-3. MODIFY is used with the SYSOUT and FLASH keywords.

MSGLEVEL({INFO | WARN | SEVERE})

specifies the minimum desired severity level of allocation messages to be returned to your program.

NCP(number)

specifies the number of READ or WRITE macros that can be issued before a CHECK macro is executed. number ranges from 1 to 255 (or from 1-99 for MVS SP 4.2.2 and earlier).

NEW

specifies that the data set does not exist, but is to be created. A disposition of CATALOG is assumed. However, you may need to specify additional keywords (such as DCB- related keywords or SMS class keywords) to define the attributes of the data set.

NOBURST

specifies that continuous forms are to be used on a 3800 printer. See BURST.

NOHOLD

specifies that the output processing for the data set is to be determined by the SYSOUT class. See HOLD.

OLD

specifies that the data set already exists and is to be allocated for exclusive use.

OPTCD(option-list)

specifies optional system services. The valid options are:

A: device addresses are to be presented in READ and WRITE macros.
B: end-of-file recognition is to be ignored for tapes.
C: chained scheduling is to be used.
E: extended search for block or available space.
F: READ or WRITE feedback should return device addresses in the form used for the control program.
H: check for and bypass.
J: the character after carriage control is the table reference character for the line.
Q: requests ASCII-to-EBCDIC or EBCDIC- to-ASCII translation for a tape.
R: relative block addressing is to be used.
T: the user totaling facility is to be used.
W: a validity check is to be performed for data written to DASD.
Z: shortened error recovery on magnetic tapes is requested.

OUTDES(descriptor-list)

specifies the list of output descriptors. Output descriptors are created by OUTPUT JCL statements. Each descriptor name can be 1 to 8 characters long.

OUTPUT

specifies output processing for a BSAM data set.

PARALLEL

indicates that a device is to be mounted for each volume given on the VOLUME keyword.

POSITION(seqno)

specifies the position of the data set on a tape volume. The number may be 1 to 9999.

PRIVATE

specifies that the private volume use attribute is to be assigned. Refer to the PRIVATE keyword in the JCL Reference for more information.

PROTECT

specifies that the data set is to be RACF protected. This keyword is used with the DATA SET, NEW, MOD, KEEP, CATALOG, and UNCATALOG keywords.

RECFM(format-list)

specifies the format for the data set's records. The following one byte codes may be used in combination:

A: ASCII printer control characters
B: blocked records
D: variable length ASCII records
F: fixed length records
M: machine code control characters
S: standard blocks (with F) or spanned records (with V)
T: overflow tracks may be used
U: undefined record lengths
V: variable length records

This keyword cannot be used with the RECORG keyword.

RECORG(vsam-org)

specifies the VSAM organization. The valid values are:

ES: entry-sequenced data set
KS: key-sequenced data set
LS: linear space data set
RS: relative record data set

This keyword is honored only if SMS is active. This keyword can not be used with the RECFM keyword.

REFDD(ddname)

specifies a previously allocated data set, the attributes of which are to be used in allocating the data set given in the DATA SET keyword (a status of NEW must also be coded). This keyword cannot be used with the LIKE keyword. REFDD is honored only if SMS is active.

RELEASE

specifies that unused space is to be release to the system when the data set is closed. This keyword is used with the BLOCK and SPACE keywords.

RETPD(days)

specifies the retention period for the data set in days. Days may range from 1 to 9999. Either this keyword or the EXPDT keyword may be used, but not both.

REUSE

specifies that the ddname is to be freed and reallocated.

ROUND

specifies that the allocated space is to be rounded up to an even cylinder. This keyword is used with the BLOCK keyword.

SECMODEL(profile[,GENERIC])

specifies the name of a RACF data set profile to be copied to the discrete profile for the data set given in the DATA SET keyword. Code GENERIC to indicate that the profile is a generic data set profile. This keyword is honored only if SMS is active.

SEGMENT(page-count)

specifies how many pages can be written to a SYSOUT data set before it is spun off. Page-count can range from 1 to 99999.

SHR

specifies that the data set already exists, and that other non-exclusive users can also access the data set.

SPACE(quantity,increment)

along with the BLOCK, AVBLOCK, TRACKS, and CYLINDERS keywords determines how much space to allocate for a data set. Quantity indicates the number of units (blocks, tracks, etc.) to be initially allocated. Increment indicates the number of units to be added to the allocation, each time the previously allocated space is filled.

SPIN({UNALLOC | NO})

specifies when a SYSOUT data set is available for printing. UNALLOC indicates the data set can be printed after the file is freed. NO indicates that the data set can be printed at the end of the current step.

STORCLAS(class)

specifies the SMS storage class name. The name can be 1-8 characters long. The storage class determines where the data set is to reside (i.e., UNIT and VOLUME). SMS must be active for this keyword to be honored.

SYSOUT[(class)]

specifies that the data set is a system output data set. You may also specify the one character class identifier. Output will be sent to the job entry subsystem. You can control how this data set will be processed by specifying additional SYSOUT-related keywords such as HOLD, SPIN, DEST, FORMS, etc.

TRACKS

specifies that the unit of space is to be tracks. This keyword is used with the SPACE keyword to determine how much space to set aside for the data set.

TRTCH(code)

specifies the 7 track tape recording technique:

C: data conversion (no translation) with odd parity
E: no conversion and even parity
ET: same as E plus BCD-to-EBCDIC translation on reads and EBCDIC-to-BCD on writes
T: no conversion and odd parity
COMP: compression
NOCOMP: no compression

UCOUNT(count)

specifies the maximum number of devices that can be allocated for this request. 59 is the largest value that can be coded.

UCS(name)

specifies the universal character set name to be used to print a SYSOUT data set. The name can be 1 to 4 bytes long.

UNCATALOG

specifies that the data set is to be removed from the catalog after it is freed. The system will, however, still keep the data set. See KEEP, DELETE, and CATALOG keywords.

UNIT(unit)

specifies the unit type to use for the data set. Unit can be a group name, a generic device type (such as TAPE), or a device address.

VOLUME(serial-list)

specifies the volume serial numbers that identify where the data set exists or where it is to be created.

Note: The system allocation routines do not always honor the volume specification, depending on whether other software, such as SMS, intervenes.

VSEQ(seqno)

specifies the volume in a multi-volume data set with which processing is to begin (for cataloged data sets only). Seqno can range from 1 to 255.

WRITER(prog-name)

specifies an installation written program to be used in writing a SYSOUT data set.

Module Name:

SWXARXT, SWXDYNA

Service Description:

ALLOCATE is a host command that is executed under the REXXTOOL host command environment. This command is used to:

Allocate a new data set.
Allocate one or more existing data sets and associate them with a ddname.
Allocate the terminal as a data set.
Allocate a SYSOUT data set.
Allocate a dummy data set

Notes:

Keywords must be separated by one or more blanks (do not use commas!).
Some ALLOCATE keywords accept lists of values (this is indicated in each keyword's description). When a list is coded, the values must be separated by blanks, commas, or both.

Returned Information:

The ALLOCATE command returns a return code in the REXX RC variable. Some return codes are common to all REXXTOOL host commands. These are documented under the topic "ADDRESS REXXTOOL". Positive RC values are returned from the dynamic allocation routines. These are:

0: Execution successful.
4: The error was due to the unavailability of a resource, a problem with the current environment, or a routine failure. The S99INFO variable will contain additional information.
8: An installation routine denied the request.
12: Invalid parameter list error. This error can occur when you specify keywords that are mutually exclusive or when a required keyword is missing.

Other REXX variables are created that return information from the dynamic allocation routines. These are:

S99ERROR: An error reason code in printable hexadecimal format. The values this variable can take, and their meanings are documented in MVS/ESA Authorized Assembler Programming Guide, GC28-1645.
S99INFO: An error information code in printable hexadecimal format. The values this variable can take, and their meanings are documented in MVS/ESA Authorized Assembler Programming Guide, GC28-1645.
S99ERSN: An SMS reason code in printable hexadecimal format. The values this variable can take, and their meanings are documented in MVS/ESA Authorized Assembler Programming Guide, GC28-1645.
S99DDN: The ddname used for the allocation. If you coded a ddname, it will appear here. If you did not code a ddname, the system generated ddname will be placed in this variable.
S99DSN: The data set name used for the allocation. If you coded more than one data set name, only the first will appear in this variable. If you did not code a data set name, the system generated data set name will be placed in this variable.
S99MSG.: An array that contains dynamic allocation messages. S99MSG.0 contains the number of messages returned. S99MSG.1 contains the first message and S99MSG.n contains the nth message. Note that messages are always returned, even if OPTIONS NOMSGS is in effect. The severity level of the messages returned is controlled by the MSGLEVEL keyword.

Examples:

Allocate an existing data set to a ddname of INDATA:

address rexxtool
"alloc fi(indata) da(olddata) shr reus"

Allocate a new data set that has 80 byte fixed block records:

address rexxtool
"alloc da(newdata) new sp(1 1) tracks lrecl(80)",
     "recfm(f,b) blksize(800) unit(sysda)"

Allocate a ddname of OUTFILE to a SYSOUT class of X:
```
address rexxtool
"alloc dd(outfile) sysout(x)"
```

Allocate a dummy data set:

address rexxtool
"alloc fi(sysprint) dummy reuse"

Allocate a new partitioned data set using a model data set:

address rexxtool
"alloc dsn('user1.newpds.data')",
     "like('user2.oldpds.data')"

Allocate a member of a PDS:

address rexxtool
"alloc fi(sysprint)",
      "da(mypds.data(member1)) reuse"