Dataset Services Interface › $DSCALL OPT=FOPEN

$DSCALL OPT=FOPEN

Combines the ALLOC option for new or existing data sets and the OPEN option into one call.

&CONTROL SHRVARS=($DS)
EXEC $DSCALL OPT=FOPEN
             DD=DD_name [ ID=path_name ]
             DSN=dataset_name
             FORMAT=dataset_format
             ORG=dataset_organization
             RLSE= { NO | YES }
             SPACE= { TRK | CYL } , pri ,sec [ ,dir ]
           [ BLKSIZE=blocksize ]
           [ DATACLS=class ]
           [ DISP= { KEEP | DELETE } [ , { KEEP | DELETE } ] ]
           [ DSNTYPE= { LIBRARY | PDSE } ]
           [ FREE= { UNAL | CLOSE } ]
           [ LRECL=logical_record_length ]
           [ MEMBER=member_name ]
           [ MGMTCLS=class ]
           [ MIGRATE= { YES | NO } ]
           [ MODE= { INPUT | OUTPUT } ]
           [ MOUNT= { NO | YES } ]
           [ STAT= {  NEW | OLD | MOD | SHR } ]
           [ STORCLS=class ]
           [ VOL=volser [ UNIT=unit ] ]

This call is used as a more simple interface than the combination of OPT=ALLOC and OPT=OPEN. It allows a single call to be made to allocate and open a new or existing cataloged data set.

Operands:

• OPT=FOPEN

  Specifies that a data set is to be allocated and opened.

• DD=DD_name

  Specifies the ddname. If this operand is omitted, a ddname is generated by the operating system.

• ID=path_name

  Specifies the ID of a path to be opened for access to the data set. The use of a path ID lets a procedure access more than one file, with the unique path ID used to identify which file is being accessed. The path ID must be specified on subsequent requests such as READ, WRITE, and CLOSE. If this operand is omitted, the ddname specified in the DD operand is used as the path ID.

• DSN=dataset_name

  Specifies the data set name to allocate and open. If the DSN operand is omitted, a temporary data set is allocated. When a temporary data set is allocated, no disposition is allowed and DELETE, DELETE is forced.

• FORMAT=dataset_format

  Specifies the data set format for the new data set. Valid values are: F, FB, FS, FBS, FA, FBA, FSA, FBSA, FM, FBM, FSM, FBSM, V, VB, VS, VBS, VBSA, VM VBM, VSM, VBSM, U, UA, UM.

• ORG=dataset_organization

  Specifies the data set organization. Valid values are: PS, PO, PSU, POU, CX, CQ, MQ, GS, TX, TQ, TR.

• RLSE={ NO | YES }

  Specifies whether to use the secondary space release option.

• SPACE={ TRK | CYL } , pri,sec { ,dir }

  Specifies the space allocation in tracks or cylinders. The SPACE type and primary allocation quantity are required. The directory allocation quantity is required if the data set is a PDS.

• BLKSIZE=blocksize

  Specifies the block size for the data set. The value must be an integer in the range 0 to 32,760.

• DATACLS=class

  Specifies the SMS data class.

• DISP={ KEEP | DELETE } [, { KEEP | DELETE } ]

  Specifies the Normal and Conditional Disposition of the data set. The disposition relates to the normal or conditional termination of your product region, not of the requesting NCL process. If KEEP is specified, the data set remains cataloged. If DELETE is specified, the data set is uncataloged and deleted.

• DSNTYPE={ LIBRARY | PDSE }

  Specifies whether you want to allocate and open a PDSE data set. The two values mean the same thing: a PDSE data set.

• MIGRATE={ YES | NO }

  Specifies whether to allocate a data set if it has been migrated. If MIGRATE=NO is specified, Dataset Services checks that the data set has been migrated (for example, by DFHSM). If the data set has been migrated, Dataset Services rejects the allocation request. If MIGRATE=YES is specified, Dataset Services issues the allocation request without checking that the data set has been migrated.

• MODE={ INPUT | OUTPUT }

  Specifies whether the data set is open for input or output.

• MOUNT={ NO | YES }

  Specifies whether a volume mount is allowed. If MOUNT=NO is specified, and an allocation request requires a volume which is off-line, the allocation request fails. If MOUNT=YES is specified and an allocation request requires a volume which is off-line, a MOUNT request for the volume is issued.

• FREE={ UNAL | CLOSE }

  Specifies whether the data set is to be deallocated by explicit request only (FREE=UNAL) or is to be deallocated when the file is closed (FREE=CLOSE).

• LRECL=logical_record_length

  Specifies the logical record length for the data set. The value must be an integer in the range 1 to 32,760.

• MEMBER=member_name

  Specifies the member name. To open a PDS that was not allocated with a member name, specify the member name in the call. If the allocation was to a member name, the member name specified in the MEMBER operand overrides it.

• MGMTCLS=class

  Specifies the SMS management class.

• STAT={ NEW | OLD | MOD | SHR }

  Specifies the status of the data set.

• STORCLS=class

  Specifies the SMS storage class.

• VOL=volser [ UNIT=unit ]

  Specifies the volume serial number and unit name for the new allocation. If the VOL operand is omitted, the operating system determines if the allocation is allowed, and may choose to allocate the data set or any volume which the requesting user is authorized for.

Return Codes:

Note: For more information about &SYSMSG, &$DSRC, and &$DSFDBK, see Return Codes and Feedback Codes.

Return Variables:

• &$DSSTAT

  Status of data set; values are OLD, MOD, or SHR

• &$DSDSN

  Full data set name with member name omitted, and true name if an alias was entered &$DSDSNTYPE Type of data set; value is LIBRARY

• &$DSMEM

  Member name if a member of a PDS &$DSID Path ID

• &$DSORG

  Data set organization; values are PS, PO, PSU, and POU

• &$DSVOL

  First volume

• &$DSUNIT

  Unit name for the volume

• &$DSRECF

  Record format; values are F, FB, FS, FBS, FA, FBA, FSA, FBSA, FM, FBM, FSM, FBSM, V, VB, VS, VBS, VBSA, VM, VBM, VSM, VBSM, U, UA, UM

• &$DSRECL

  Record length

• &$DSRECA

  Actual usable record length. If the record format is variable length, then the value is record length minus 4. In all other cases, the value is the same as record length.

• &$DSBLKS

  Block size

• &$DSDDNAME

  DDname from the allocation, as supplied or as generated by the operating system

• &$DSSTORCLS

  SMS storage class if SMS is active for this data set

• &$DSMGMTCLS

  SMS management class if SMS is active for this data set

• &$DSDATACLS

  SMS data class if SMS is active for this data set

• &$DSDYNEC

  DYNALLOC error code

• &$DSDYNIC

  DYNALLOC information code

Example: OPT=FOPEN

EXEC $DSCALL OPT=FOPEN DSN=SYS.WORK.DEV01 MEMBER=TEST01 +
   STAT=OLD MODE=OUTPUT

Notes:

Only cataloged data sets are supported. Unit and volume parameters are not supported by this function.

Most non-VSAM data sets are allocated. IS and DA data sets are not supported. If MEMBER= was specified, the member is opened. If the allocation was for a sequential data set, the data set is opened.