RSTS36F (Restore System/36 File)

RSTS36F Command syntax diagram

 

Purpose

The Restore System/36 File (RSTS36F) command reads a file, creates a database physical or logical file (if it does not already exist), and copies any data into the file. This command restores to the system a single file or a group of files that are saved together using the System/36 save procedure. The input file can be a diskette file, tape file, or a database physical file on the iSeries 400. The file must have been created either on a System/36 using the SAVE system OCL procedure (or the equivalent OCL call of the $COPY SSP utility), or on the iSeries 400 using the SAVS36F CL command.

The RSTS36F command accepts a diskette file created on a System/36, System/34, or System/32 using the $COPY utility. The RSTS36F command accepts tape files created on a System/36. System/34 or System/32 diskette offline multiple-volume files are not accepted by this command.

The RSTS36F command accepts a diskette file created as a compressed file.

If the file being restored does not exist in the library specified on the TOLIB parameter, it is created. A physical file member is added using the name syntax 'Myymmdd', which identifies the original creation date of the file. This naming convention is needed by the System/36 environment in order to support date-differentiated files.

If a file name is specified for the TOFILE parameter, the name must meet the iSeries 400 naming standards. For more information about iSeries 400 naming conventions, see object naming rules.

If TOFILE(*SET) is specified, the files that are restored may have names that contain characters not allowed in an iSeries 400 simple object name. In this case, the file name is changed to an iSeries 400 extended name and the file is restored.

If the name contains a blank, a single quotation mark, a double quotation mark, an asterisk, a question mark, or a device control character (hexadecimal 00 through 3F or hexadecimal FF), the invalid characters are replaced with underlines. The file is then restored using the resulting simple or extended name; for example, A*_? would become "A___"). If a file already exists with this new name, it is handled like any other name (see the MBROPT parameter).

If a file name is changed because of invalid characters, an informational message (CPF 2C1F) is sent to the recursion level above the program that is running this command. If the name is changed from a simple name to an extended name, no message is sent.

If the restore function creates the file and the file was not previously secured, the new file is owned by the user issuing the RSTS36F command and the file is created with a default authority of *ALL (that is the same as AUT(*ALL)).

If the file was saved from the S/36 where the attributes were an extend value of zero or no value was specified, a default value of 32,767 divided by the record length is assigned. If an extend value of zero is required, use the Change Physical File (CHGPF) command (after the restore operation is completed) to set SIZE(*EXTEND) to zero. If the file was saved from the iSeries 400, the file is restored and the extend value does not change.

This function is intended only for exchanging files with a System/36.

 

Restrictions

  1. This command is shipped with public *EXCLUDE authority.

  2. The following authorities are required when running on a system using resource security:

    • *USE, *SECADM, and *ALLOBJ authorities for this command

    • *USE authority for the library specified in the TOLIB parameter

    • *CHANGE authority for the library specified in the TOLIB parameter when restoring a file that does not already exist on the system

    • *CHANGE and *OBJMGMT authority for the existing file (needed to add a new member) when restoring a date-differentiated physical file and a file by the same name but with a different creation date

    • *ALL authority for the file when restoring to an existing physical file with the same creation date and MBROPT(*REPLACE) specified

    • *CHANGE authority for the based-on physical file (this physical file was referred to as the parent file on System/36) if the file being restored is a System/36 alternative index file (that is, a logical file)

    • *USE authority for the diskette device description object and *USE authority for device file QSYSDKT in library QSYS, when restoring from diskette

    • *USE authority for the tape device description object and *USE authority for device file QSYSTAP in library QSYS, when restoring from tape

    • *USE authority for the file and *USE authority for the library that contains the file (PHYFILE parameter) if restoring from a database physical file

    • If the file doesn't exist on the system but a file authorization holder object by the same name does exist, *ALL authority or ownership for the authorization holder object

  3. There is no replace function supported when restoring System/36 alternative index files (logical files). If restoring an alternative index file, no file object by the same name can already exist in the specified library.

  4. If restoring a logical file, the based-on physical file must already exist in the library specified for the TOLIB parameter.

  5. The iSeries 400 files that are the same as the System/36 date-differentiated files are multiple-member physical files. Date-differentiated alternative index files are not supported. The data for a physical file is stored in a member that is named using the syntax 'Myymmdd' where 'yymmdd' represents the original creation date (in year/month/day format) of the file.

    Because all members of a physical file share the same file attributes (for example, record length and key information), date-differentiated files with the same name that are restored to the same library are required to have the same file attributes. If an attribute mismatch is present, the files are not restored.

  6. Object-level and record-level functions, including read operations, should not be used for a file being restored by the RSTS36F command. If another operation is being done at the same time on the file (for example, moving the file or reading or adding records), the restore operation stops if it cannot allocate the file.

 

Required Parameters

TOFILE
Specifies the name of a single file that is restored to the system or that a group of files that are all saved at the same time using the System/36 SAVE procedure (a Save All Set) are to be restored to the system.

*SET: A group of files from a Save All Set are restored to the system.

file-name: Specify the file name given to a single file when the file is restored to the system.

TOLIB
Specifies the library that will contain the file being restored from the input file.

DEV
Specifies the names of the devices used for the restore operation. Each device name must already be known on the system by a device description.

*PHYFILE: The input file is the database physical file specified by the PHYFILE parameter.

device-name: Specify the name of the diskette device, the media library device, or the names of tape devices that are used for the operation. If more than one tape device is used, specify the names of the devices in the order in which they are used. When more than one tape volume is used, using more than one tape device permits one tape volume to be rewound or unloaded while another tape device processes the next tape volume. More information on device names is in the APPC, APPN, and HPR topic in the Information Center.

 

Optional Parameters

SET
Specifies the name used to identify the Save All Set files saved on the diskette or tape by the SAVE procedure or the $COPY utility on the System/36, System/34, or System/32.

#SAVE: The files are restored from a Save All Set with a set identifier of #SAVE.

set-identifier: Specify the set identifier of the Save All Set that is restored. Valid values range from 1 through 8 characters. The first character must be alphabetic (A through Z, #, $, or @). The remaining characters can be any combination of characters (numeric, alphabetic, and special) except a comma (,), an apostrophe ('), or a blank.

IGCDTA
Specifies whether the file being restored can contain double-byte character set (DBCS) data.

*NO: The file being restored cannot contain DBCS data. If a file already exists by the name specified on the TOFILE parameter in the specified library and the file allows DBCS data, an informational message is sent and the restore operation continues. The resulting file allows DBCS data (the file's IGC attributes are not changed by the restore operation).

*YES: The file processes DBCS data.

FROMLABEL
Specifies the label of the diskette or tape file that contains the file being copied to the iSeries 400 (it identifies the input file for the restore operation). Up to 8 characters can be used to label the diskette or tape file.

For a group restore operation, this parameter can be used to specify the diskette or tape file label with a save all set where the restore operation is to begin. If no value is specified, the restore operation begins with the first file in the set.

If no value is specified, the value of the TOFILE parameter is used as the diskette or tape label. If the TOFILE parameter is an extended name, the characters between the quotation marks are used as the label. For example, specifying TOFILE("MIKE&BOB") and no FROMLABEL parameter would be the same as specifying FROMLABEL('MIKE&BOB').

CRTDATE
Specifies the creation date of the object.

The date must be entered in the job date format (DATFMT); if separators, specified by the job date separator character (DATSEP), are used, the value must be enclosed in apostrophes. The CRTDATE parameter cannot be specified if the FROMLABEL parameter is not specified.

For diskettes coming from a System/36, there may be multiple files on one diskette with the same name and different creation dates. Specifying a value for the CRTDATE parameter is the only way of choosing which diskette file to use.

For tapes from System/36 or iSeries 400, there can be multiple files on a tape with the same name. The user can use the CRTDATE parameter or SEQNBR parameter to choose the correct file. If a numeric SEQNBR parameter and the CRTDATE parameter are specified, the SEQNBR parameter takes precedence (if the file at the specified sequence number has a different creation date, the restore operation ends).

Specify the creation date of the tape or diskette file used for the restore operation. The date specified is changed to Julian format (cyyddd) for tape files and international format (yymmdd) for diskette files.

If no value is specified, the diskette file or tape file creation date is not used to select the input file. For diskette, take the first file in the diskette volume table of contents (VTOC) with the name specified on the FROMLABEL parameter. For tape, take the first file on the tape with the name specified on the FROMLABEL parameter. If the previous tape operation had specified ENDOPT(*LEAVE), the search for a matching file does not start at the beginning of the tape reel.

DATDIFF
Specifies whether the restore operation should allow date-differentiated files (that is, multiple files with the same name but different file creation dates).

*NO: Date-differentiated files are not allowed.

If a file already exists by the name specified on the TOFILE parameter in the specified library, and the file contains a member with a different creation date (as determined by the member name), an error message is sent and the file is not restored.

If a file already exists by the name specified on the TOFILE parameter in the specified library, and the file contains a member with the same creation date (as determined by the member name), either the data in that member is replaced (if MBROPT(*REPLACE) is specified) or an error message is sent (if MBROPT(*NOREPLACE) is specified).

If no file exists by the name specified on the TOFILE parameter in the specified library, the file is restored normally.

*YES: Date-differentiated files are allowed.

If a file already exists by the name specified on the TOFILE parameter in the specified library, and the file contains a member with a different creation date (as determined by the member name), a member is added to the file (only if the file attributes match), and the file's data is restored into the new member.

If a file already exists by the name specified on the TOFILE parameter in the specified library, and the file contains a member with the same creation date (as determined by the member name), either the data in that member is replaced (if MBROPT(*REPLACE) is specified) or an error message is sent (if MBROPT(*NOREPLACE) is specified).

If no file exists by the name specified on the TOFILE parameter in the specified library, the file is restored normally.

SEQNBR
Specifies, only when tape is used, which sequence number is used for the restore operation.

*SEARCH: The volume in the device is searched for a data file with an identifier that matches the FROMLABEL parameter value; when a match is found, the data file is restored. If the last operation on the tape device specified ENDOPT(*LEAVE), the file search starts with the data file at the current tape position. Otherwise, the search starts with the first data file on the tape volume. The header label name from the file found by the SEQNBR parameter is compared to the name specified for the FROMLABEL parameter. If the names are the same, the restore operation can continue. If the names are different, the restore operation ends.

file-sequence-number: Specify the sequence number of the file that is used. Valid values range from 1 through 9999.

VOL
Specifies the volume identifiers of the tape volumes or diskette volumes from which the objects are being restored. The volumes must be in the same order as they were when the library was saved. If the library was known to the system before the restore operation, the system can verify whether the volumes put on tape contain the current version of the library. The volume that contains the beginning of the file to be restored should be placed in the tape or diskette unit. More information on this parameter is in commonly used parameters.

*MOUNTED: The objects are restored from the volumes placed in the device specified on the DEV parameter.

volume-identifier: Specify the volume identifiers of the tapes or diskettes to be used for restoring the file. For each tape or diskette volume name, up to 6 characters can be specified using any combination of letters and digits. Up to 50 volume names can be specified.

ENDOPT
Specifies the operation that is automatically performed on the tape volume after the operation ends. If more than one volume is included, this parameter applies only to the last tape volume used; all other tape volumes are rewound and unloaded when the end of the tape is reached.

Note: This parameter is ignored if a diskette device is specified in the DEV parameter.

*REWIND: The tape is automatically rewound, but not unloaded, after the operation has ended.

*LEAVE: The tape does not rewind or unload after the operation ends. It remains at the current position on the tape drive.

*UNLOAD: The tape is automatically rewound and unloaded after the operation ends.

PHYFILE
Specifies the qualified name of the database physical file that is used as the input file for the restore operation.

The file must have a record length of 256 bytes.

If the specified file does not exist or is not a physical file, the file is not restored. If the physical file contains multiple members, the first member of the file is used.

The name of the physical file can be qualified by one of the following library values:

*LIBL: All libraries in the job's library list are searched until the first match is found.

*CURLIB: The current library for the job is searched. If no library is specified as the current library for the job, the QGPL library is used.

library-name: Specify the name of the library to be searched.

file-name: Specify the name of the database file that is used as the input file for the restore operation.

MBROPT
Specifies whether the new records replace or are added to the existing records.

*NOREPLACE: If a file already exists by the name specified on the TOFILE parameter in the specified library, and the file contains a member with the same creation date (as determined by the member name), an error message is sent and the data in that member is not replaced.

*REPLACE: If a file already exists by the name specified on the TOFILE parameter in the specified library, and the file contains a member with the same creation date as the file being restored, the data in that member of the file is replaced.

Examples for RSTS36F

Example 1: Restoring From Diskette 

RSTS36F  TOFILE(ACCTRCV)  TOLIB(QS36F)  DEV(I1)
  CRTDATE('01/22/85')  VOL(SAVE1)

This command restores the file ACCTRCV into library QS36F. Assuming that I1 is the name of a diskette device description object, the file is restored from the diskette placed in the diskette device. The diskette must have a volume name of SAVE1. The diskette file used for the restore must have a file label of ACCTRCV and a creation date of January 22, 1985 (assuming the job date format is *MDY and the date separator is a '/').

Example 2: Restoring From Tape 

RSTS36F  TOFILE(PAY.VIEW)  TOLIB(PAYLIB)  DEV(T1)
  FROMLABEL('P*V')  ENDOPT(*LEAVE)

The file P*V is restored from device T1 as a file named PAY.VIEW in library PAYLIB. Assuming T1 is a tape device, the file is copied from one or more tapes that are on device T1. No check is made on the tape volume name. When the restore operation ends, the tape is left positioned at the end of tape file P*V.

Example 3: Restoring from a Physical File 

RSTS36F  TOFILE(ACCTPAY)  TOLIB(QS36F)  DEV(*PHYFILE)
  PHYFILE(NETLIB/SENDFILE)

This command restores the file ACCTPAY in library QS36F from physical file SENDFILE in library NETLIB.

Example 4: Specifying Sequence Numbers 

RSTS36F  TOFILE(*SET)  TOLIB(QS36F)  DEV(T1 T2)
  SET(PAYFILES)  FROMLABEL(FILE10)  MBROPT(*REPLACE)
  DATDIFF(*YES)  SEQNBR(*SEARCH)  VOL(*MOUNTED)
  ENDOPT(*REWIND)

This command restores a subset of the files in the save all set called PAYFILES to library QS36F from tape. The restore operation begins with a tape file whose label is file 10. If one of the files being restored already exists in library QS36F with the same creation date as the saved file, the file is replaced. If a file already exists in library QS36F with a different creation date, a new date-differentiated number is added to the file. The restore operation uses the tape volumes that are placed in tape drives T1 and T2. After the restore operation is complete, the last tape volume is rewound to the beginning of the tape.

Error messages for RSTS36F

*ESCAPE Messages

CPF2C4A
Device &1 not correct for command.
CPF2C4B
Duplicate device &1 specified in device name list.
CPF2C4C
Diskette device &1 included in multiple device specification.
CPF2C4D
Not all files were restored.
CPF2C4E
Restore operation ended before all files were restored.
CPF2C45
Input file &1 cannot be processed by RSTS36F.
CPF2C47
Existing file &1 or member &3 in library &2 not replaced.
CPF2C48
Input file &1 in &2 not correct for command.
CPF2C49
Output file &1 in &2 not correct for command.
CPF2C5A
Alternate index file &1 in library &2 not replaced.
CPF2C5E
Input file &1 in &2 not correct for command.
CPF2C50
File description for file &1 is not available.
CPF2C52
Error occurred during attempt to create file &1 in library &2.
CPF2C53
Member &3 not added to file &1 in library &2 because error occurred.
CPF9810
Library &1 not found.
CPF9812
File &1 in library &2 not found.
CPF9814
Device &1 not found.
CPF9820
Not authorized to use library &1.
CPF9822
Not authorized to file &1 in library &2.
CPF9825
Not authorized to device &1.
CPF9826
Cannot allocate file &2.
CPF9830
Cannot assign library &1.
CPF9831
Cannot assign device &1.
CPF9845
Error occurred while opening file &1.
CPF9847
Error occurred while closing file &1 in library &2.
CPF9848
Cannot open file &1 in library &2 member &3.
CPF9849
Error while processing file &1 in library &2 member &3.

*STATUS Messages

CPI2C11
Copying records to file &1 in library &2 member &3.