Macro type: type S (E form/L form/D form/C form); see "Macro types"
The IMPORT macro catalogs files for which the calling job has the ownership rights and which are stored on private disks or Net-Storage volumes of the NETSTOR type. The DMS takes the file attributes from the F1 label of the private disk or from the catalog of the Net-Storage volume of the NETSTOR type and places them in the catalog entry. 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. The macro can process partially qualified file names, which means that the user can import several files using a single macro.
When importing file generation groups with generations stored on different disks, it should be noted that generations are 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 by means of an IMPORT or FILE macro (STATE=FOREIGN).
The functions of the macros IMPORT and ERASE (operands CATALOG or DELETE-OR-EXPORT and VOLUME, respectively) 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 later imported, DMS creates catalog entries only for those files which begin on the volume (i.e. files which received space on the volume during their primary allocation).
Notes
Co-owners of a user ID can create permanent files under this ID.
Locked entries can be imported from the F1 label or from the catalog of the Net-Storage volume of the NETSTOR type. However, if entries in the user catalog have to be replaced (REPLACE=YES/ABS), the entries must not be locked and write access must be permitted.
Format
Operation | Operands |
|
|
| |
|
Operand descriptions
AREA
Specifies the output area for the IMPORT macro. This operand may be omitted if LIST=NO is specified.
= (addr,length)
addr | symbolic address of the output area |
length | length of the output area. |
DEVICE = device
Device type on which the volume is to be mounted. See the device table in the „System installation“ manual [16] for possible entries for “vsn”. The new device types introduced after BS2000 Version 9.5 are only supported in conjunction with the VERSION=1 operand. For Net-Storage volumes the volume type NETSTOR must be specified instead of the device type.
Every specification of a disk device type which is known to the system is handled like the STDDISK specification.
GEN
For file generation groups:
specifies whether only the group entry or also the file generations stored on the same private disk is/are to be cataloged.
= YES
If the group entry is on the private disk, DMS catalogs the FGG and all related generations which are on this disk. If there is no group entry on the disk or in the user catalog, no file generations are cataloged.
= NO
DMS transfers only the group entry for the FGG to the catalog.
LIST
Specifies how macro execution is to be logged (see "Programming notes").
= YES
Macro execution is logged.
= NO
No information about macro execution is returned.
= ONLY
Causes execution of the IMPORT macro to be simulated, not actually carried out, i.e. the user receives a SYSLST log which shows how the IMPORT macro would have been executed. The log contains (depending on “pathname”) a list of the files on the volume specified by VOLUME, together with the messages and information returned by the IMPORT macro.
DMS does not check, at this time, whether file locks or protection attributes would prevent files from being imported. For the actual import, the user must ensure that the files are not locked and that write access is permitted.
MF
The forms of the MF operand are described in detail in the appendix ("Macro types"). In all macros differentiated solely by the MF operand (MF=L/E/D/C), the version operand must have the same value.
NUSERID = userid
Only permitted for system administration:
User ID under which the file is to be cataloged. The new user ID is specified without $ and without “.”.
A file on private disk is assigned the new user ID both in the file catalog and in the F1 label of the disk.
A BS2000 file on a Net-Storage volume is assigned the new user ID both in file catalog and in the catalog of the Net-Storage volume.
A node file, by contrast, cannot be cataloged under the new user ID as an owner of node files may not be modified. In this case the import is rejected with return code D.
pathname
Designates the files, file generation groups or file generations to be cataloged, with:
<c-string 1..54: filename 1..54> (a partially qualified file name is also permitted).
If “pathname” is not 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.
“pathname” means [$userid.]filename
userid
User ID: the user can only import files for which he/she has owner rights. Default user ID: the user ID of the current job (i.e. of the SET-LOGON-PARAMETERS or LOGON command).
filename
Fully or partially qualified name of a file, file generation group or file generation.
For file generations and file generation groups, the group entry must be created before cataloging the generations!
PREFIX
This operand is only relevant in combination with MF=D/C.
Default value: I
= pre
Specifies a prefix for all names used in a Dsect. Only a single-character is permitted.
= *
Specifies that no prefix is to be used.
PVSID = catid
Specifies the pubset in which the files are to be cataloged. If this is omitted, the catalog entries are created under the default catalog ID of the user ID.
When a Net-Storage volume is specified in the VOLUME operand, this Net-Storage volume must be assigned the pubset to whose catalog the entries are imported. The catalog entry in the pubset is then updated with the data of the Net-Storage volume’s catalog entry.
REPLACE
Specifies whether an existing “old” catalog entry is to be overwritten.
= NO
DMS does not overwrite any existing catalog entry.
= YES
The old catalog entry is deleted if it does not agree with the specifications in the IMPORT macro:
The cataloged file is stored on a public disk: the catalog entry is deleted, which means that the public file is erased (providing the protection attributes permit this and the file is not locked; otherwise, the old catalog entry is left unchanged).
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 stored on a Net-Storage volume. A file on the same Net-Storage volume with the same name 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 another Net-Storage volume or on the same Net-Storage volume but which has a different name (not a node file) is imported: the catalog entry is overwritten and the file is thus deleted (if this is not prevented by a file lock or protection attributes, otherwise the old entry is retained). In this case deleting the file means:
A BS2000 file on Net-Storage of the type NETSTOR is also deleted on the Net-Storage volume.
A node file is retained on the Net-Storage volume.
The cataloged file is contained on private disk and begins on the disk specified in the VOLUME operand: the catalog entry is not deleted (exported). A file of the same name is not imported.
= ABS
The old catalog entry is overwritten even if the catalog entry and the specifications in the IMPORT command match each other. The return code shows whether the entry was overwritten (return code 8) or whether a file lock prevented overwriting (return code 9).
VERSION = 1
Controls macro generation. The operand list and, if applicable, the SVC valid for BS2000 versions from V9.5 upwards are generated.
Default value: | the operand list and the SVC are generated as for BS2000 versions < V9.5. |
VOLUME = vsn
The volume serial number (“vsn”) of the volume on which the files to be imported are stored.
If files are to be imported from a Net-Storage (DEVICE = NETSTOR), the archive number ("vsn") is used to decide which type of Net-Storage volume is involved. Files on a Net-Storage volume of the NETSTOR type are imported.
Programming notes
Each element returned is 56 bytes long and has the following structure:
pathname (54 bytes) + Return code (2 bytes)
Return codes
Only the rightmost byte of the return code is of importance to the user. This byte supplies additional information on the processing of the IMPORT macro if the return code in register 15 is X'00'.
Return | Meaning |
C'0' | There was no file with the same name and a new catalog entry has been created. |
C'1' | There was already a file with the same name and this was overwritten; |
C'2' | A file with the same name exists but was not overwritten; the REPLACE operand had the value NO |
C'3' | A file with the same name exists and could not be erased due to the protection function (ACCESS=READ, WRPASS, etc.) or the file is locked because it is being processed. |
C'4' | System error during catalog access. |
C'5' | The file is already cataloged and is stored on the volume specified in the VOLUME operand. |
C'6' | System error during access to the F1 label of the private disk or to the catalog of the Net-Storage volume. |
C'7' | Invalid attempt to import a file generation: the absolute generation number of the generation to be imported conflicts with the limits defined in the group entry. |
C'8' | A catalog entry already existed for the specified disk and has been replaced. |
C'9' | A catalog entry already exists for the specified disk, but the file is locked. |
C'A' | The path name of the file to be imported (together with catalog ID and $userid) is longer than 54 characters. |
C'B' | Error while accessing the Net-Storage. |
C'C' | The file to be imported is larger than 32 GB, but the pubst specified does not permit files which are larger than 32 GB. |
C'D' | Node files may not be imported to a different user ID. |
A file on the volume has been processed successfully if the return code is C'0', C'1', C'5' or C'8'.
The following table describes the left byte of the return code. This byte is only significant if the system administrator is using the NUSERID operand. The specifications refer to the entries in the system catalog under Ouserid.
Return code for | Meaning |
C'0' | There is no entry in the system catalog under the userid entered in the F1 label of a private disk or in the catalog of the Net-Storage volume. |
C'1' | A file cataloged with the same name was deleted. |
C'2' | A file of the same name already exists; the value of the REPLACE operand was NO. |
C'3' | The cataloged file is protected (error on deleting this file). |
C'4' | System error on reading the catalog. |
C'D' | Node files may not be imported to a different user ID. |
System behavior for an overflow of the output area: A user area that is too small is indicated by R15 = 05AB. The import operation is carried out in any case. For a layout of the output area, see above; end criterion X'FF' to offset: last entry +X'36'.
The return code is placed in register 15. If the macro executes normally, the contents of register 15 are set to null. The possible return codes of DMS can be generated by the IDEMS macro.