Operating System BS2000 OS DX V1.0 (en)

&pagelevel(3)&pagelevel

Create catalog entry for files (file import)

Component:	BS2000
Functional area:	File processing
Domain:	FILE FILE-GENERATION-GROUP
Privileges:	STD-PROCESSING SAT-FILE-EVALUATION SAT-FILE-MANAGEMENT TSOS
Routing code:	$ (with NBCONOPI=N) or E (with NBCONOPI=Y)

Function

The IMPORT-FILE command creates the catalog entries for files which are contained on private volumes or Net-Storage volumes of the NETSTOR type (i.e. imports them). The catalog entries for files held on private volumes or Net-Storage volumes of the NETSTOR type can be deleted (i.e. they can be exported) using the EXPORT-FILE command. If there is already a catalog entry for a file on private disk or on Net-Storage volume of the NETSTOR type, it can be updated on the basis of the F1 label of the private disk or the file catalog of the Net-Storage volume (SUPPORT=*BY-FILENAME(...)).
Files on a Net-Storage volume of the NETVOL type cannot be imported because there is no file catalog on a Net-Storage volume of the NETVOL type.

When importing file generation groups with generations stored on different disks, it should be noted that generations will be cataloged only if the group entry already exists in the system catalog or is kept on the first disk to be imported. Otherwise, the catalog entries for the generations imported before the group entry will be missing. These generations must then be cataloged afterwards using an IMPORT-FILE command.

Privileged functions

For catalog entries on private volumes or Net-Storage volumes systems support (TSOS privilege) can use the NEW-USER operand to specify a user ID under which the files are to be cataloged.

If the IMPORT-FILE command with SUPPORT=*DISK is entered without a file name being explicitly specified (this corresponds to FILE-NAME=*ALL), unlike with nonprivileged users the entire F1 label of the private disk or the entire catalog of the Net-Storage volume is imported.

By default, systems support (TSOS privilege) is a co-owner of all the files (and can, therefore, create files under all user logons). When SECOS is used, this co-ownership can be restricted for permanent files.

Systems support can generate files under any user ID (TSOS privilege). In conjunction with the SECOS software product a user can allow other user IDs to act as co-owners. Co-owners of a user ID are then also allowed to import files under that ID.

Notes

The functions of the commands IMPORT-FILE and EXPORT-FILE are not exact opposites: When a volume is exported, DMS deletes the catalog entries for all files which occupy storage space on this volume.
If the same volume is re-imported, DMS creates catalog entries only for those files which begin on the volume (i.e. files which were given space on this volume by their primary allocation).

The IMPORT-FILE command can be used, for example, to catalog files which were created under the user ID of the calling job and which are contained on private disks or Net-Storage volumes. DMS copies the file attributes from the F1 label of the private disk or the catalog of the Net-Storage volume into the catalog entry. Partially qualified file names can be processed, so that one command can be used to import a number of files.

Locked entries can be imported from the F1 label or from the catalog of the Net-Storage volume. However, if entries in the user catalog have to be replaced (REPLACE-OLD-FILES=*YES/*ABS), the entries must not be locked and write access must be permitted.
When importing or exporting file generation groups which are stored on private disks, the following must be noted:
- An IMPORT-FILE command will only catalog generations for which there is a group entry, either on the designated disk or already present in the system catalog. For a file generation group which is split across several disks and is not yet cataloged, this has the following consequences: If the first disk which is imported is not the one containing the group entry, and this latter is only subsequently imported, then the catalog entries for the generations held on the first disk will be missing. Remedy: issue an IMPORT-FILE command for each of the volumes affected, or for the uncataloged generations.
- If a private disk only holds individual generations from a file generation group, but not the group entry, then when this volume is exported, “gaps” can result in the file generation group (i.e. if the VOLUME operand specifies a private disk which contains the file generation but not its group entry). This gap affects only the catalog entry, the file generation group remains complete on the disk.

Format

IMPORT-FILE

SUPPORT = DISK(...) / TAPE(...) / *BY-FILE-NAME(...)
	*DISK(...)
		\|	VOLUME = <alphanum-name 1..6>
		\|	,DEVICE-TYPE = *BY-VOLUME-CATALOG / <device>
		\|	,FILE-NAME = *ALL / <partial-filename 2..50 without-cat-id> / <filename 1..51 without-cat-id>
		\|	,TYPE-OF-FILE = [ *ANY ] (...)
		\|		[ *ANY ](...)
		\|			\|	GENERATIONS = YES / NO
		\|	,REPLACE-OLD-FILES = NO / YES / *ABS
		\|	,OUTPUT = SYSLST / SYSOUT / ALL / NO
		\|	,NEW-USER = *NONE / <name 1..8>
		\|	,PUBSET = *STD / <cat-id 1..4>
	*TAPE(...)
		\|	VOLUME = *ANY / list-poss(255): <alphanum-name 1..6>
		\|	,DEVICE-TYPE = *BY-VOLUME-CATALOG / <device>
		\|	,FILE-NAME = <filename 1..54>
		\|	,PREMOUNT-LIST = *NONE / list-poss(255): <integer 0..255>
	*BY-FILE-NAME(...)
		\|	FILE-NAME = <filename 1..54 without-vers>
		\|	,INFORMATION = NAME-AND-SPACE / SPACE-SUMMARY / *ALL-ATTRIBUTES /
		\|					[PARAMETERS](...) / STATISTICS / *MINIMUM
		\|		[*PARAMETERS](...)
		\|			\|	STANDARD = NO / YES
		\|			\|	,PROTECTION = NO / YES
		\|			\|	,FILE = NO / YES / *FILE
		\|			\|	,PASSWORDS = NO / YES
		\|			\|	,ALLOCATION = NO / YES
		\|			\|	,BACKUP = NO / YES
		\|			\|	,HISTORY = NO / YES
		\|			\|	,ORGANIZATION = NO / YES
		\|			\|	,SECURITY = NO / YES
		\|	,OUTPUT = SYSOUT / NONE / SYSLST(...) / PRINTER(...) /
		\|					<filename 1..54 without-gen-vers>(...)
		\|		*SYSLST(...)
		\|			\|	FORM-NAME = STD / FILE-NAME
		\|		*PRINTER(...)
		\|			\|	FORM-NAME = STD / FILE-NAME
		\|		<filename>(...)
		\|			\|	FORM-NAME = STD / FILE-NAME

Operands

SUPPORT = *DISK(...) / *TAPE(...) / *BY-FILE-NAME(...)
Specifies whether the files are to be imported from disk or from tape, or whether the catalog entries of the files on private disk or Net-Storage volumes are to be updated using the catalog entry.

SUPPORT = *DISK(...)
The files to be imported are stored on private disk or on a Net-Storage volume.

VOLUME = <alphanum-name 1..6>
Volume serial number (VSN) of the volume on which the files to be imported are stored.

DEVICE-TYPE = *BY-VOLUME-CATALOG / <device>
Identifies the type of device on which the volume is to be mounted.
Only device types known within the system are accepted. In interactive mode, the possible device types are displayed with DEVICE-TYPE=?.
The volume type NETSTOR must be specified for Net-Storage volumes.
Every specification of a disk device type is known in the system is handled like the STDDISK specification.
The permissible specifications for DEVICE-TYPE can also be found in the device table in section "Device type table" (device type column). The devices available on the system can be listed with the SHOW-DEVICE-CONFIGURATION command.

DEVICE-TYPE = *BY-VOLUME-CATALOG
The device type is determined via the MAREN device substitution function if the MAREN subsystem is available.

FILE-NAME = *ALL / <partial-filename 2..50 without-cat-id> / <filename 1..51 without-cat-id>
Specifies the files, file generation groups or file generations which are to be cataloged. When the default FILE-NAME=*ALL is specified, DMS catalogs all files, etc. which are stored under the user ID of the current job on the volume specified in the VOLUME operand. For privileged users, see "Privileged functions".

For file generations/file generation groups, create the group entry before cataloging the generations!

Only files contained on the volume specified in VOLUME will be imported.

FILE-NAME = *ALL
All the files contained on the volume specified in VOLUME will be imported.

TYPE-OF-FILE = *ANY(...)
Specifies whether the file generations from the specified file generation group are to be imported also. It is only meaningful to use this operand if no file generation is to be imported (GENERATIONS=*NO).

GENERATIONS = *YES / *NO
For file generation groups GENERATIONS specifies whether only the group entry is to be cataloged, or the file generations stored on the same private disk are also to be cataloged.

GENERATIONS = *YES
If the group entry is on the private disk, DMS will catalog the FGG and all its generations which begin on this disk. If there is no group entry on the disk or in the user catalog, no file generations will be cataloged.

GENERATIONS = *NO
DMS transfers just the group entry for the FGG to the catalog.

REPLACE-OLD-FILES = *NO / *YES / *ABS
Specifies whether an existing “old” catalog entry is to be overwritten.

REPLACE-OLD-FILES = *NO
DMS does not overwrite the existing catalog entry.

REPLACE-OLD-FILES = *YES
The old catalog entry will be deleted if it does not match the details specified in the IMPORT-FILE command.

The following situations should be distinguished:

- - The cataloged file is stored on a public disk: the catalog entry is overwritten, which means that the public file is deleted (providing the protection attributes permit this and the file is not locked; otherwise, the old catalog entry is left unchanged).
  - The cataloged file is stored on a Net-Storage volume. A file with the same name on the same Net-Storage volume is not imported and the catalog entry is not deleted.
  - The cataloged file is stored on a Net-Storage volume. A file on private disk, on a different Net-Storage volume or on the same Net-Storage volume but with a different name (not a node file) is imported. The catalog entry is overwritten and the file therefore deleted (providing the protection attributes permit this and the file is not locked; otherwise, the old entry remains unchanged). In this case, deleting the file means:
    - A BS2000 file on Net-Storage is also deleted on the Net-Storage volume.
    - A node file on the Net-Storage volume is retained.
    In contrast to BS2000 files, node files cannot be imported to another user ID as the owner of a node file may not be changed.
  - The cataloged file is on private disk, but begins on a volume other than the one specified in the VOLUME operand: the catalog entry is overwritten (exported) (providing the protection attributes permit this and the file is not locked; otherwise, the old entry remains unchanged).
  - The cataloged file is on private disk, and begins on the disk specified in the VOLUME operand: The catalog entry will not be deleted (exported). A file with the same name will not be imported.

REPLACE-OLD-FILES = *ABS
The old catalog entry is overwritten even if the catalog entry and the specifications in the IMPORT-FILE command match. Special return codes show whether the entry was overwritten (special return code 8) or whether a file lock prevented overwriting (special return code 3).

The following situations should be distinguished:

- - The cataloged file is stored on a public disk: the catalog entry is overwritten, which means that the public file is deleted (providing the protection attributes permit this and the file is not locked; otherwise, the old catalog entry is left unchanged).
  - The cataloged file is stored on a Net-Storage volume. Difference to the operand value *YES: A file with the same name on the Net-Storage volume is imported. The catalog entry is overwritten. If a file lock or the protection attributes prevent this, the old entry is retained.
  - The cataloged file is stored on a Net-Storage volume. A file on private disk, on another Net-Storage volume or with a different name on the same Net-Storage volume (not a node file) is imported: the catalog entry is overwritten and the file is consequently deleted. If a file lock or the protection attributes prevent this, the old entry is retained.
    In contrast to BS2000 files, node files cannot be imported to another user ID as the owner of a node file may not be changed.
  - The cataloged file is on private disk, but begins on a volume other than the one specified in the VOLUME operand: the catalog entry is overwritten (providing the protection attributes permit this and the file is not locked; otherwise, the old entry remains unchanged).
  - The cataloged file is on private disk, and begins on the disk specified in the VOLUME operand. Difference to the operand value *YES:The catalog entry is overwritten (providing the protection attributes permit this and the file is not locked; otherwise the old catalog entry remains unchanged). Even if there is a file with the same name, the file will be imported.

OUTPUT = *SYSLST / *SYSOUT / *ALL / *NO
Specifies how the execution of the command is to be logged.

OUTPUT = *SYSLST
The execution of commands will be logged on SYSLST; this log contains the special return codes and message texts (see table "Special return codes and messages for SUPPORT=*DISK").

OUTPUT = *SYSOUT
The execution of commands will be logged on SYSOUT; only the special return codes and file names are output in this log (see table "Special return codes and messages for SUPPORT=*DISK").

OUTPUT = *ALL
The execution of commands will be logged on SYSLST and SYSOUT (see the OUTPUT=*SYSLST and OUTPUT=*SYSOUT operands).

OUTPUT = *NO
No return information on the execution of the command will be output.

NEW-USER = *NONE / <name 1..8>
User ID under which the file is to be cataloged.
A new user ID is assigned to a file on a private disk both in the file catalog and in the F1 label of the disk. The new user ID is assigned to a BS2000 file on a Net-Storage volume both in the file catalog and in the catalog of the Net-Storage volume. A node file, on the other hand, cannot be cataloged under the new user ID as the owner of a node file may not be changed. In this case, t he import is rejected with return code D.

PUBSET = *STD / <cat-id 1..4>
Specifies the pubset on which the files are to be cataloged. If none is specified, the catalog entries are created in the file catalog of the default pubset for the user’s ID.
If a Net-Storage volume is specified in the VOLUME operand, the Net-Storage volume must be assigned to the pubset specified here. Only in this case is the file catalog of the specified pubset updated on the basis of the catalog entries of the Net-Storage volume.

PUBSET = *STD
The default setting is *STD, i.e. the catalog entries are set up under the file catalog of the default pubset of the user ID (see the output field DEFAULT-PUBSET in the SHOW-USER-ATTRIBUTES command).

PUBSET = <cat-id 1..4>
Specifies the pubset on which the files are to be cataloged.

SUPPORT = *TAPE(...)
Specifies that the file to be imported is located on a tape or tape cartridge.

VOLUME = list-poss(255): <alphanum-name 1..6> / *ANY
The VSN of the tape on which the file to be imported is stored.

VOLUME = *ANY
The volume is determined via the MAREN volume substitution function if the MAREN subsystem is available.

DEVICE-TYPE = *BY-VOLUME-CATALOG / <device>
The device type to which the required tape is assigned. Only device types or volume types known within the system are accepted. In interactive mode, the possible device and volume types are displayed with DEVICE-TYPE=?.

DEVICE-TYPE = *BY-VOLUME-CATALOG
The device type is determined via the MAREN device substitution function if the MAREN subsystem is available.

FILE-NAME = <filename 1..54>
The file will only be imported if it is held on the specified tape.

PREMOUNT-LIST = *NONE / list-poss(255): <integer 0..255>
The tape sequence number of the tape to be mounted.

PREMOUNT-LIST = *NONE
The first of the volumes specified in the VOLUME operand will be requested.

PREMOUNT-LIST = list-poss(255): <integer 0..255>
Issues a MOUNT message on the console requesting the mounting of tapes or suppresses the request. The tape sequence numbers specified here relate to the VSNs listed in the VOLUME operand. Specifying PREMOUNT-LIST=0 has the effect that no tapes will be requested. Otherwise, use: PREMOUNT-LIST=(n[,n+1][,n+2]...) with n=1.

SUPPORT = *BY-FILE-NAME(...)
Specifies for which files on private disk or Net-Storage volumes the catalog entry in the TSOSCAT is to be updated on the basis of the entry on the volume (F1 label or catalog of the Net-Storage volume).

FILE-NAME = <filename 1..54 without-vers>
The name of the file whose catalog attributes are to be copied from the F1 label of a private disk or the catalog of the Net-Storage volume. If the entry in the F1 label of the private disk or the catalog of the Net-Storage volume no longer exists, the catalog entry is deleted.
Only the catalog entry is output for a file on public disk.

INFORMATION = *NAME-AND-SPACE / *SPACE-SUMMARY / *ALL-ATTRIBUTES / *PARAMETERS(...) / *STATISTICS / *MINIMUM
Type of information to be displayed.

INFORMATION = *NAME-AND-SPACE
For the selected files, the number of PAM pages used will be output with the file name, in alphabetical order of file name. This is the only possible operand value if the output is not routed to SYSOUT (see the OUTPUT operand).

INFORMATION = *SPACE-SUMMARY
Provides information on the storage space allocation of the files and file generations identified in the current command.

INFORMATION = *ALL-ATTRIBUTES
Returns all the information that is contained in the catalog (NAME-AND-SPACE, PARAMETERS) for the selected files. The output fields are listed in alphabetical order with a further explanation of their possible values in the table “Meaning of the output fields” at the end of the operand description section.

INFORMATION = *PARAMETERS(...)
Returns only the selected information for the files in question. The information from the catalog is logically arranged into information blocks. Only those information blocks which are explicitly selected by the user are output. Total lines with the overall storage space allocation for each selected file are shown at the end of the returned information (see INFORMATION=SPACE-SUMMARY).

STANDARD = *NO / *YES
Specifies whether standard information is to be output.

The STANDARD operand is only supported for compatibility reasons. It is not offered in guided dialog. STANDARD=*YES is equivalent to INFORMATION=*PAR(ORGANIZATION=*YES, ALLOCATION=*YES).

PROTECTION = *NO / *YES
Specifies whether information concerning the file protection and expiration date is to be output.

The PROTECTION operand is only supported for compatibility reasons. It is not offered in guided dialog. PROTECTION=*YES is equivalent to

INFORMATION=*PAR(ORGANIZATION=*YES,SECURITY=*YES, BACKUP=*YES).

FILE = *NO / *YES
Output: storage space used in PAM pages, and file attributes.

The FILE operand is only supported for compatibility reasons. It is not offered in guided dialog. FILE=*YES is equivalent to INFORMATION=*PAR(ORGANIZATION=*YES,ALLOCATION=*YES).

PASSWORDS = *NO / *YES
Specifies whether the information on passwords is to be output. A header line with the title “PASSWORDS” and a line with the information on file passwords (which corresponds to the first information line of the security block) are output.

PASSWORDS = *NO
No PASSWORD information is to be output.

PASSWORDS = *YES
The first line of the security block is output.
This line provides information on the types of passwords which protect a file or file generation group. The passwords themselves are not shown. If a user forgets a file password, only the system administrator can help him. The following attributes are output:

Header line with the word “PASSWORDS”

EXEC-PASS	protection with execution password
READ-PASS	protection with read password
WRITE-PASS	protection with write password

ALLOCATION = *NO / *YES
Outputs the allocation block for the selected files, i.e. all file attributes that affect the allocation of storage space. The allocation block contains the following attributes:
Header line with the word “ALLOCATION”

DEVICE-TYPE	device type for volume
EXTENTS	total number of extents for the file
HIGH-US-PA	highest used PAM page
NUM-OF-EXT	Number of extents
S-ALLOC	secondary allocation for file extension
SUPPORT	type of volume
VOLUME	volume serial number

BACKUP = *NO / *YES
Outputs the backup block for the selected files, i.e. all file attributes that affect backups. The backup block contains the following attributes:
Header line with the word “BACKUP”

BACK-CLASS	backup level for ARCHIVE or HSMS
MIGRATE	indicates whether the file may be migrated
SAVED-PAG	indicates whether the file must always be fully saved
VERSION	internal attribute for incremental saving with the ARCHIVE or HSMS utility routine.

HISTORY = *NO / *YES
Outputs the history block for the selected files, i.e. all file attributes related to the file history. The history block contains the following attributes:
Header line with the word “HISTORY”

ACC-COUNT	access counter
ACC-DATE	date of last access
ACC-TIME	time of last access
CHANG-DATE	date the file was last changed (written to)
CHANG-TIME	time the file was last changed (written to)
CRE-DATE	creation date
CRE-TIME	time of creation
S-ALLO-NUM	number of secondary allocations

ORGANIZATION = *NO / *YES
Outputs the organization block for the selected files, i.e. all file attributes related to the structure of the file. The organization block contains the following attributes:

AVAIL	availability
BLK-CONTR	Block control information
BUF-LEN	block type (standard or nonstandard block)
COD-CH-SET	coded character set (CCS) with XHCS support
FILE-STRUC	access method when the file was created
KEY-LEN	Length of ISAM key
KEY-POS	position of ISAM key
LOG-FL-LEN	length of logical ISAM flag
PROPA-VAL	propagation of ISAM flag
REC-FORM	Record format
REC-SIZE	Record length
VAL-FL-LEN	length of ISAM value flag

The information block for file generation groups begins with the header line GENERATION-INFO and contains the following attributes:

BASE-NUM	base value for relative generation numbers
DEVICE-TYPE	device type for volume
FIRST-GEN	most recent or last cataloged file generation
LAST-GEN	oldest existing file generation
MAXIMUM	maximum number of simultaneously cataloged generations
OVERFL-OPT	overflow option when maximum number is reached
VOLUME	volume serial number

SECURITY = *NO / *YES
Outputs the security block for the selected files, i.e. all file attributes related to the file security. The security block contains the following attributes:
Header line with the word “SECURITY”

ACCESS	type of access (standard access control)
ACL	file protection with ACL (only supported for reasons of compatibility)
AUDIT	file monitoring
DESTROY	data automatically destroyed on deletion
ENCRYPTION	encryption method
EXEC-PASS	protection with execution password
EXPIR-DATE	date on which the file may be changed again
EXPIR-TIME	time relative to EXPIR-DATE
FREE-DEL-D	free-for-deletion date
FREE-DEL-T	time relative to free-for-deletion date
GUARD-READ	read protection using a guard
GUARD-WRIT	write protection using a guard
GUARD-EXEC	protection with execute guard
GROUP	access rights of user class “group” (BASIC-ACL)
OTHERS	access rights of user class “others” (BASIC-ACL)
OWNER	access rights of file owner (BASIC-ACL)
READ-PASS	protection with read password
SP-REL-LOCK	type of access (standard access control)
USER-ACC	file protection with ACL (only supported for reasons of compatibility)
WRITE-PASS	file monitoring

INFORMATION = *STATISTICS
Returns information on storage space allocation for all selected files. The storage space allocations for files and file generation groups are output separately and include additional information for each type of volume (public disks, private disks, and tapes). Files for which no entry has been made in the volume list are indicated in the output for public disks (NO VSN).

INFORMATION = *MINIMUM
Outputs a line of information with the most important file attributes in summarized form for each selected file. This line contains brief information on the FILE-STRUCTURE, passwords, highest activated access protection level, the number of reserved PAM pages, and the file name. The brief information is indicated as follows:

- - the access method with which the file was created: indicated by the first letter in the value of FILE-STRUCTURE;
  - information for read, write, and execute passwords: shown in each case with “Y” or “N” to indicate whether the corresponding password was assigned;
  - information on the highest activated access control method: see the PROTECTION-ACTIVE operand.
  - When standard access control is the highest protection:
    - USER-ACCESS with “Y” for ALL-USERS or SPECIAL, or with “N” for OWNER-ONLY
    - ACCESS with “W” for write access or “R” for read access only.
  - When the basic access control list (BASIC-ACL) is the highest protection: the access rights assigned for each of the user groups OWNER, GROUP and OTHERS are shown (“RWX” or “-” for an access right that has not been set).
  - When access control using GUARDS is the highest protection: the value “GUARDS” and the protected access mode (“RWX” or “-” for an access mode not granted) are shown.

OUTPUT = *SYSOUT / *NONE / *SYSLST(...) / *PRINTER(...) / <filename 1..54 without-gen-vers>(...)
Defines the destination to which the information is output.

OUTPUT = *NONE
Suppresses the output of information. This specification is typically useful when only the command return code is to be evaluated in a procedure.

OUTPUT = *SYSOUT
The information will be presented in tabular form on SYSOUT.

OUTPUT = *SYSLST(...)
The information will be presented in tabular form on SYSLST. SYSLST will automatically be output on a printer at the end of the job. The format of the output will be determined as follows:

FORM-NAME = *STD / *FILE-NAME
The default value is *STD, i.e. the information will be presented in tabular form. If *FILE-NAME is specified, then a simple list of file names will be output.

OUTPUT = *PRINTER(...)
The information will be presented in tabular format and output to printer (as an immediate SPOOL job, which will be output with CONTROL-CHARACTERS= *EBCDIC).

FORM-NAME = *STD / *FILE-NAME
The default value is *STD, i.e. the information will be presented in tabular form. If *FILE-NAME is specified, then a simple list of file names will be output.

OUTPUT = <filename 1..54 without-gen-vers>(...)
The information will be written to the specified file; the format of the output can be determined as follows.

FORM-NAME = *STD / *FILE-NAME
The default value is *STD, i.e. the information will be presented in tabular form. If *FILE-NAME is specified, then a simple list of file names will be output.

Return codes

(SC2)	SC1	Maincode	Meaning/Guaranteed messages
	0	CMD0001	Command executed
2	0	DMS051E	Inconsistency in private disk pool or operand error detected
2	0	DMS054A	Insufficient disk space or access to disk not possible
2	0	DMS05B6	Invalid time conversion from UTC to LT
	1	CMD0202	Syntax or semantic error in command
	32	DMS0584	A state that does not allow the function to continue was reported during processing
	32	DMS05C7	Unexpected internal error in DMS
	64	CMD0216	Privilege errors
	64	DMS0501	Requested catalog not available
	64	DMS0512	Requested catalog not found
	64	DMS051B	Requested user ID not in pubset Guaranteed message: DMS051B
	64	DMS051C	User not authorized to access pubset Guaranteed message: DMS051C
	64	DMS0533	Requested file not cataloged in pubset Guaranteed message: DMS0533
	64	DMS0535	Specified file not shareable
	64	DMS053E	File already cataloged on private volume
	64	DMS0555	Specified file name already cataloged
	64	DMS055C	Catalog entry not found on the specified private disk or Net-Storage volume
	64	DMS0585	Error detected when processing catalog or multiprocessor system
	64	DMS0586	It is not possible to access or reserve a volume at present
	64	DMS0587	Use of the specified command has been restricted by the system administrator
	64	DMS05F8	DMS error reported
	64	DMS05FC	Specified user ID not in HOME pubset
	64	DMS05FE	Requested file(s) not found
	64	DMS0653	File on Net-Storage volume of the NETVOL type cannot be imported
	64	DMS06C4	File generation group not yet cataloged
	64	DMS06CC	No file corresponding to specified operands
	64	DMS06D0	Specified file generation does not exist
	64	DMS06FF	BCAM connection severed
	128	DMS0506	Function not executed due to change in master
	130	DMS0524	System address space exhausted
	130	DMS053C	Insufficient space for catalog file on pubset
	130	DMS0582	File is currently locked or being used and cannot be processed
	130	DMS0585	Error detected when processing catalog or multiprocessor system Guaranteed message: DMS053C
	130	DMS0586	It is not possible to access or reserve a volume at present
	130	DMS0594	Not enough virtual memory available
	130	DMS05C8	Maximum permitted number of files reached

Special return codes and messages for SUPPORT=*DISK

The following codes (SYSOUT) or messages (SYSLST) can be output :

Code on SYSOUT	Message on SYSLST	Meaning
0	FILE DID NOT EXIST	There was no file with the same name and a new catalog entry has been created.
1	FILE HAS BEEN ERASED	A file of the same name already existed and has been overwritten.
2	FILE EXISTS / REPLACE-OLD-FILES=*NO	A file of the same name existed but was not overwritten; the REPLACE-OLD-FILES operand had the value *NO.
3	FILE IS PROTECTED (ERASE ERROR OR FILE IS IN USE)	A file of the same name existed and could not be deleted because of active protection functions (ACCESS=READ, password protection etc.) or the file is locked because it is being processed.
4	ERROR ON CATALOG ACCESS	System error during catalog access.
5	FILE ALREADY ON PRIVATE	The file is already cataloged and is stored on the volume specified in the VOLUME operand.
6	ERROR ON VTOC ACCESS	System error when accessing the F1 label of the private disk or the catalog of the Net-Storage volume.
7	GENERATION OUT OF RANGE	Invalid attempts to import a file generation: the absolute generation number of the generation to be imported conflicts with the limits defined in the group entry.
8	C.E. HAS BEEN REPLACED	A catalog entry already existed for the specified disk and has been replaced.
A	INVALID FILENAME	The path name for the file to be imported (including pvsid and userid) is more than 54 characters long. Pathname = :catid:$.userid:filename It should be noted that the pathname is made up from details taken from two different operands in the command. The file name is specified in the FILE-NAME operand, the catalog ID in the PUBLIC-VOLUME-SET operand. For a 1-character catalog ID, the file name must not be longer than 51 characters. For a 4-character catalog ID, the file name may be up to 48 characters long.
T	ERROR ON NET-STORAGE ACCESS	System error during Net-Storage access.
C	LARGE FILE NOT ALLOWED	The file to be imported is larger than 32 GB, but the pubset specified does not permit files larger than 32 GB.
D	RENAME OF NODE-FILES NOT ALLOWED	The importing of node files to a foreign user ID is not permitted.

Table 52: IMPORT-FILE: Special return codes and messages

Examples

Example 1: Importing files from private disks

/imp-file sup=disk(vol=work01,dev-type=d3435,file-name=*all, output=*sysout) —————————————————————————— (1)

%  0 :2OS2:$USER1.MAX.LIB 
%  0 :2OS2:$USER1.MAX.PRIV-FILE.1 
%  0 :2OS2:$USER1.MAX.PRIV-FILE.2 
%  0 :2OS2:$USER1.MAX.PRIV-FILE.3

/show-file-attr max.,select=(support=*priv) —————————————————————————— (2)

%       210*:2OS2:$USER1.MAX.LIB 
%         3*:2OS2:$USER1.MAX.PRIV-FILE.1 
%         3*:2OS2:$USER1.MAX.PRIV-FILE.2 
%         3*:2OS2:$USER1.MAX.PRIV-FILE.3  
%:2OS2: PRDISC:      4 FILES RES=       219 FRE=        29 REL=        21 PAGES

(1)	All files of the user USER1 on the private disk WORK01 (device type D3435) are to be imported. The messages output during the process are to be sent to SYSOUT.
(2)	The output indicates that four files were successfully imported (as is evident from the return code 0 in each case). The command causes the catalog entries for files which have names beginning with MAX. and which are stored on private disk to be shown (the files which were previously imported).

Example 2: Exporting and importing tape files

/show-file-attr support=*tape,inf=(alloc=*yes,org=*yes) ————————————— (1)

% :2OS2:$USER1.MAX.TAPE-FILE.1
% ------------------------------- ORGANIZATION -------------------------------
% FILE-STRUC = SAM BUF-LEN = STD(1) BLK-CONTR = PAMKEY
% REC-FORM = (V,N) REC-SIZE = 2044
% CODE = EBCDIC LABEL = (STD,1) FILE-SEQ = 1
% BLK-OFFSET = 4
% ------------------------------- ALLOCATION -------------------------------
% SUPPORT = PVT BLK-COUNT = 1
% EXTENTS VOLUME DEVICE-TYPE EXTENTS VOLUME DEVICE-TYPE
% D2326K TAPE-C4
% :2OS2:$USER1.MAX.TAPE-FILE.2
% ------------------------------- ORGANIZATION -------------------------------
% FILE-STRUC = SAM BUF-LEN = STD(1) BLK-CONTR = PAMKEY
% REC-FORM = (V,N) REC-SIZE = 2044
% CODE = EBCDIC LABEL = (STD,1) FILE-SEQ = 2
% BLK-OFFSET = 4
% ------------------------------- ALLOCATION -------------------------------
% SUPPORT = PVT BLK-COUNT = 1
% EXTENTS VOLUME DEVICE-TYPE EXTENTS VOLUME DEVICE-TYPE
% D2326K TAPE-C4
%:2OS2: TAPE : 2 FILES

/export-file vol=d2326k,file=name(*all),output=*sysout ———————————————— (2)

% DMS0516 DELETE FILE(S) ':2OS2:$USER1.' ? REPLY (Y=YES; N=NO; T=TERMINATE COM
MAND; ?=EXPLAIN ADDITIONAL OPTIONS)?y ——————————————————————————————————— (3)
% DMS0800 SPECIFIED FILE ':2OS2:$USER1.MAX.TAPE-FILE.1' DELETED
% DMS0800 SPECIFIED FILE ':2OS2:$USER1.MAX.TAPE-FILE.2' DELETED

/show-file-attr support=tape ————————————————— (4)

% DMS06CC NO FILE CORRESPONDING TO SPECIFIED OPERANDS

/import-file sup=*tape(vol=d2326k,dev-type=tape-c4, file-name=max.tape-file.1) ————————————————— (5) /import-file sup=*tape(vol=d2326k,dev-type=tape-c4, file-name=max.tape-file.2) ————————————————— (6)

/show-file-attr support=*tape,inf=(org=*yes,alloc=*yes) ————————————— (7)

% :2OS2:$USER1.MAX.TAPE-FILE.1
% ------------------------------- ORGANIZATION -------------------------------
% FILE-STRUC = NONE BUF-LEN = NONE BLK-CONTR = NONE
% REC-FORM = NONE REC-SIZE = 0
% CODE = NONE LABEL = NONE FILE-SEQ = NONE
% BLK-OFFSET = 0
% ------------------------------- ALLOCATION -------------------------------
% SUPPORT = PVT BLK-COUNT = 0
% EXTENTS VOLUME DEVICE-TYPE EXTENTS VOLUME DEVICE-TYPE
% ( D2326K TAPE-C4 )
% :2OS2:$USER1.MAX.TAPE-FILE.2
% ------------------------------- ORGANIZATION -------------------------------
% FILE-STRUC = NONE BUF-LEN = NONE BLK-CONTR = NONE
% REC-FORM = NONE REC-SIZE = 0
% CODE = NONE LABEL = NONE FILE-SEQ = NONE
% BLK-OFFSET = 0
% ------------------------------- ALLOCATION -------------------------------
% SUPPORT = PVT BLK-COUNT = 0
% EXTENTS VOLUME DEVICE-TYPE EXTENTS VOLUME DEVICE-TYPE
% ( D2326K TAPE-C4 )
%:2OS2: TAPE : 2 FILES

/copy-file from=max.tape-file.1,to=#copy.tape-1 ——————————————— (8) /show-file-attr max.tape-file.1,inf=(org=*yes) —————————————— (9)

% :2OS2:$USER1.MAX.TAPE-FILE.1
% ------------------------------- ORGANIZATION -------------------------------
% FILE-STRUC = SAM BUF-LEN = STD(1) BLK-CONTR = PAMKEY
% REC-FORM = (V,N) REC-SIZE = 2044
% CODE = EBCDIC LABEL = (STD,1) FILE-SEQ = 1
% BLK-OFFSET = 4
%:2OS2: TAPE : 1 FILE

/add-file-link link=dmcopy11,file-name=max.tape-file.2,sup=*tape(f-seq=2) ——(10) /copy-file from=max.tape-file.2,to=#copy.tape-2 ———————————————— (11) /show-file-attr max.tape-file.2,inf=(org=*yes) ——————————————— (12)

% :2OS2:$USER1.MAX.TAPE-FILE.2
% ------------------------------- ORGANIZATION -------------------------------
% FILE-STRUC = SAM BUF-LEN = STD(1) BLK-CONTR = PAMKEY
% REC-FORM = (V,N) REC-SIZE = 2044
% CODE = EBCDIC LABEL = (STD,1) FILE-SEQ = 2
% BLK-OFFSET = 4
%:2OS2: TAPE : 1 FILE

(1)	Output of all catalog entries for tape files of the user ID USER1 showing information on the file organization and volume allocation. Two tape files exist on the magnetic tape cartridge D2326K. The file MAX.TAPE-FILE.2 follows the file MAX.TAPE-FILE.1 (see the FILE-SEQ output fields).
(2)	The tape files on the tape cartridge D2326K are exported. Messages are output to SYSOUT.
(3)	Since more than one file is involved here, a prompt is issued to request confirmation. When this prompt is confirmed with Y, the catalog entries for the tape files MAX.TAPE-FILE.1 and MAX.TAPE-FILE.2 are deleted.
(4)	No catalog entries for tape files exist at this point.
(5)	Imports the tape file MAX.TAPE-FILE.1 from the tape cartridge D2326K.
(6)	Imports the tape file MAX.TAPE-FILE.2 from the tape cartridge D2326K.
(7)	Output of the catalog entries for the tape files showing information on the file organization and volumes. Only the catalog entries have been created so far (as if with CREATE-FILE). The file attributes have not yet been entered (value NONE or 0). The volume D2326K has only been registered (the value is still in parentheses). See also the output under step.
(8)	The tape file MAX.TAPE-FILE.1 is now accessed with the COPY-FILE command. The file is read and its contents are copied into the temporary file #COPY.TAPE-1.
(9)	The catalog entry for the tape file MAX.TAPE-FILE.1
(10)	A TFT entry with the default link name DMCOPY11 is created for the tape file MAX.TAPE-FILE.2. This file is then opened by COPY-FILE as the input file. Since MAX.TAPE-FILE.2 is the second file on the tape cartridge D2326K, FILE-SEQUENCE=2 was defined in the TFT entry. Without this specification, FILE-SEQUENCE=1 would have been assumed as in the case of MAX.TAPE-FILE.1.
(11)	The tape file MAX.TAPE-FILE.2 is now accessed with the COPY-FILE command. The file is read and its contents are copied into the temporary file #COPY.TAPE-2.
(12)	The catalog entry for the tape file MAX.TAPE-FILE.2

Example 3: Updating catalog entries for files on private disk

/show-file-attr select=(sup=*priv,gen=*yes),inf=*all ———————————————— (1)

%0000000000*:2OS2:$USER1.MAX.GROUP.1 (FGG)
% ------------------------------- HISTORY -------------------------------
% CRE-DATE = 2012-01-18 ACC-DATE = NONE CHANG-DATE = 2012-01-18
% CRE-TIME = 00:00:00 ACC-TIME = NONE CHANG-TIME = 00:00:00
% ACC-COUNT = 0 S-ALLO-NUM = 0
% ------------------------------- SECURITY -------------------------------
% READ-PASS = NONE WRITE-PASS = NONE EXEC-PASS = NONE
% USER-ACC = OWNER-ONLY ACCESS = WRITE ACL = NO
% AUDIT = NONE FREE-DEL-D = *NONE EXPIR-DATE = 2012-01-18
% DESTROY = NO FREE-DEL-T = *NONE EXPIR-TIME = 00:00:00
% SP-REL-LOCK = NO ENCRYPTION = *NONE
% ------------------------------- BACKUP -------------------------------
% BACK-CLASS = A SAVED-PAG = COMPL-FILE VERSION = 0
% MIGRATE = ALLOWED
% #BACK-VERS = 0
% ------------------------------- GENERATION-INFO ----------------------------
% MAXIMUM = 3 BASE-NUM = 0 OVERFL-OPT = DELETE-ALL
% FIRST-GEN = 4 LAST-GEN = 4
% EXTENTS VOLUME DEVICE-TYPE
% WORK01 D3435
%0000000003*:2OS2:$USER1.MAX.GROUP.1(*0004)
% ------------------------------- HISTORY -------------------------------
% CRE-DATE = NONE ACC-DATE = NONE CHANG-DATE = NONE
% CRE-TIME = NONE ACC-TIME = NONE CHANG-TIME = NONE
% ACC-COUNT = 0 S-ALLO-NUM = 0
% ------------------------------- SECURITY -------------------------------
% READ-PASS = NONE WRITE-PASS = NONE EXEC-PASS = NONE
% USER-ACC = OWNER-ONLY ACCESS = WRITE ACL = NO
% AUDIT = NONE FREE-DEL-D = *NONE EXPIR-DATE = NONE
% DESTROY = NO FREE-DEL-T = *NONE EXPIR-TIME = NONE
% SP-REL-LOCK= NO ENCRYPTION = *NONE
% ------------------------------- BACKUP -------------------------------
% BACK-CLASS = A SAVED-PAG = COMPL-FILE VERSION = 0
% MIGRATE = ALLOWED
% #BACK-VERS = 0
% ------------------------------- ORGANIZATION -------------------------------
% FILE-STRUC = NONE BUF-LEN = NONE BLK-CONTR = NONE
% IO(USAGE) = READ-WRITE IO(PERF) = STD DISK-WRITE = IMMEDIATE
% REC-FORM = NONE REC-SIZE = 0
% AVAIL = *STD
% ------------------------------- ALLOCATION -------------------------------
% SUPPORT = PVT S-ALLOC = 9 HIGH-US-PA = 0
% EXTENTS VOLUME DEVICE-TYPE EXTENTS VOLUME DEVICE-TYPE
% 1 WORK01 D3435
% NUM-OF-EXT = 1
%:2OS2: PRDISC: 2 FILES RES= 3 FRE= 3 REL= 0 PAGES

/write-text '*** Datum: &(DATE(FORMAT=*GERMAN)) ***' ————————————— (2)

*** Datum: 18.03.2012 ***

/import-file sup=*by-file-name(file-name=max.group(*4)),inf=*all ————————— (3)

% DMS0533 REQUESTED FILE NOT CATALOGED IN PUBSET '2OS2'. COMMAND TERMINATED

/import-file sup=*by-file-name(file-name=max.group.1),inf=*all ———————— (4)

% DMS0533 REQUESTED FILE NOT CATALOGED IN PUBSET '2OS2'. COMMAND TERMINATED

/show-file-attr max.group*,select=(sup=*priv) ———————————————— (5)

% DMS06CC NO FILE CORRESPONDING TO SPECIFIED OPERANDS

(1)	Returns information on all catalog entries for files on private disk. The private disk WORK01 contains the file generation group MAX.GROUP.1 with generation 0004. The group entry was created on 18.01.2012. Generation 0004 is merely cataloged. It has not yet been opened with OPEN=*OUTPUT.
(2)	Output of the current date using WRITE-TEXT to replace an expression in the output text of the builtin DATE( ) function (a component of the software product SDF-P) in order to indicate the date in German. The date is 18.03.2012.
(3)	The private disk WORK01 was made available to the user by the system administration only for the month of January. At the start of February, all the data on this disk was deleted in an VOLIN run, but the entry in the file catalog was not updated. The entry in the catalog file was not updated in the process. The IMPORT-FILE command is now used in order to update the entry for generation 0004 of the file generation group MAX.FILE.GROUP.1* from the VTOC of the private disk. Since the VTOC of the private disk WORK01 does not contain an entry for this generation, the catalog entry is also deleted, and message DMS0533 is output.
(4)	The IMPORT-FILE command updates the group entry of the file generation group MAX.FILE.GROUP.1 from the VTOC of the private disk: Since the VTOC of the private disk WORK01 does not contain an entry for this generation, the catalog entry is also deleted, and message DMS0533 is output.
(5)	The output shows that there are no catalog entries for files whose name starts with MAX.GROUP.

Your Browser is not longer supported

Please use Google Chrome, Mozilla Firefox or Microsoft Edge to view the page correctly

IMPORT-FILE

Function

Privileged functions

Notes

Format

Operands

Return codes

Special return codes and messages for SUPPORT=*DISK

Examples

Example 1: Importing files from private disks

Example 2: Exporting and importing tape files

Example 3: Updating catalog entries for files on private disk