Import pubset
Component: | BS2000 |
Functional area: | Pubset and MRSCAT management |
Domain: | MULTI-CATALOG-AND-PUBSET-MGMT |
Privileges: | TSOS |
Routing code: | R |
Function
This command creates a separate task under the control of the calling task. This task performs IMPORT processing asynchronously to the calling task. This task requests all the resources.
Each volume set of an SM pubset is imported separately.
The F5 labels are read in and reconstructed if necessary. The mnemonic names of the disks belonging to the pubset are entered or updated in the SVL of the system disk (pubres). The name of the system disk is stored in the pubset’s MRSCAT entry. The user catalog is opened and the specified pubset is set to “accessible”. The user tables that contain the current user information are set up in the memory. Access to this pubset is then permitted. Depending on the specifications made by system support staff in the ADD-MASTER-CATALOG-ENTRY command, automatic start of SPEEDCAT with or without task switching is supported. SPOOL is notified and the spoolout jobs are transferred to TYPE5/KP or TYPE4. User jobs in the wait state HELD-BY-CALENDAR or HELD-BY-PUBSET because the imported pubset was previously unavailable are released.
When a pubset is imported with ACTUAL-JOIN=*FIRST all files and job variables of the user ID TSOS are retained. Files and job variables of all other users are deleted.
The change in the availability of a pubset is notified to all active processors in the network.
A number of different pubsets can be imported to a processor.
Format
IMPORT-PUBSET | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Operands
PUBSET = <cat-id 1..4>
Catalog ID of the pubset to be imported.
ACTUAL-JOIN = *STD / *ZIP / *FIRST
Specifies handling of the user catalog during import.
ACTUAL-JOIN = *STD
The effect of this operand is governed by the RECONSTRUCT-USERCAT operand. With RECONSTRUCT-USERCAT=*NO, the existing user catalog ($TSOS.SYSSRPM) is opened. The effect of the *RESET and *BACKUP operand values is described under the RECONSTRUCT-USERCAT operand.
ACTUAL-JOIN = *ZIP
This operand value may only be specified in the event of disk storage space bottlenecks to prevent a log file and the BACKUP file for the user catalog being generated by user administration. Apart from that, this operand value is treated in exactly the same way as *STD, in other words, processing is governed by the value of the RECONSTRUCT-USERCAT operand.
ACTUAL-JOIN = *FIRST
Creates a new user catalog containing only the system user IDs. The TSOS user IDs remain intact. The RECONSTRUCT-USERCAT operand is ignored.
MONJV = *NONE / <filename 1..54 without-gen-vers>
Specifies whether a monitoring job variable is set. This variable is set to the following values during import:
$I | at the start of import |
$R | at the end of import if the entire pubset has been successfully imported |
$A | import was terminated due to an error |
$W | if a shared pubset has been imported and the availability of the master processor has not yet been confirmed |
This operand should only be specified if the JV software product is used.
Notes
- The specified job variable only becomes the monitoring job variable if the pubset has not been imported.
The job variable must already be cataloged, otherwise it is not set. However, IMPORT processing continues even if the job variable is not defined.
JV-PASSWORD = *NONE / <c-string 1..4> / <x-string 1..8> / <integer -2147483639..2147483639>
Password of the job variable if this is write-protected.
The operand JV-PASSWORD is defined as “secret”:
The password entered is not logged.
The input field is automatically blanked out in the guided dialog.
In unguided dialog and foreground procedures, the entry *SECRET or ^, SDF provides a blanked out input field for inputting the password.
RESIDENT-BUFFERS = *STD / *NO / *YES
Specifies whether resident or nonresident buffers are to be created (also see "Notes").
RESIDENT-BUFFERS = *STD
The value specified in the MRSCAT entry applies.
RESIDENT-BUFFERS = *NO
A nonresident buffer is created.
RESIDENT-BUFFERS = *YES
A resident buffer is created.
NUMBER-OF-BUFFERS = *STD / <integer 1..255>
Defines the number of buffers.
NUMBER-OF-BUFFERS = *STD
The value specified in the MRSCAT entry applies.
NUMBER-OF-BUFFERS = <integer 1..255>
The specified number of buffers (minimum 6; see "Notes") is created.
USE = *STD / *SHARE / *EXCLUSIVE(...) / *FROM-REMOTE(...)
Defines the mode of access to the imported pubset. Please observe the relevant conditions and requirements.
USE = *STD
The value specified in the MRSCAT entry applies.
USE = *SHARE
Specifying this operand only makes sense if the MRSCAT is configured for shareability. The pubset is to be imported as a shared pubset.
USE = *EXCLUSIVE(...)
The pubset is to be imported as an exclusive pubset. A volume set can also be imported in order to perform recovery.
CONVERT-VOLUME-SET = *NO / *YES
Specifies whether a normal import is to be performed or whether the volume set of a destroyed SM pubset is to be converted into an SF pubset.
CONVERT-VOLUME-SET = *NO
A normal import is to be performed.
CONVERT-VOLUME-SET = *YES
A volume set that is to be converted into an SF pubset was specified in the PUBSET operand. This function can be used to re-establish the accessibility of data in the volume sets of an SM pubset whose control volume set has become inoperative. Please take account of the notes on "IMPORT-PUBSET".
USE = *FROM-REMOTE(...)
Makes the catalog of a “remote-imported” pubset available if MRSCAT entries were defined after HIPLEX MSCF network startup.
HOST-NAME = *NONE / <alphanum-name 1..8>
BCAM name of the partner host owning the pubset. There has to be an MSCF link to the computer.
SHARER-TYPE = *STD / *SLAVE / *MASTER(...)
Specifying this operand only makes sense if the MRSCAT is configured for shareability or if the USE operand is set to *SHARE. Defines the ownership of the pubset. Please observe the relevant conditions and requirements.
SHARER-TYPE = *STD
The system selects the system automatically on the basis of the pubset’s attributes:
If the shared pubset already has a master or another system is explicitly predefined as the master (with /SET-PUBSET-ATTRIBUTES), the system selects SHARER-TYPE=*SLAVE.
In all other cases it selects SHARER-TYPE=*MASTER.
SHARER-TYPE = *SLAVE
The home system is to be a slave sharer.
SHARER-TYPE = *MASTER(...)
The home system is to take over the as yet unassigned ownership of the pubset being imported.
MASTER-CHANGE = *NO
The home system is to take over the as yet unassigned ownership of the pubset being imported. The command is rejected if the pubset has already been imported.
MASTER-CHANGE = *YES
Systems support can initiate an explicit master change from a slave system following the failure of the master or after the EXPORT-PUBSET command was issued with MASTER-CHANGE=*YES from the master.
An explicit master change is not possible in the case of BACKUP-MASTER=*NONE and ALTERNATE-BACKUP=*NONE (see the SET-PUBSET-ATTRIBUTES command). An explicit master change can be used in the following situations:
The master change initiated automatically by watchdog at a specified backup master was rejected with an error.
An automatic master change is hindered by BACKUP-MASTER=*NONE and ALTERNATE-BACKUP=*BY-OPERATOR.
SESSION-CHECK-MSG = *YES / *NO
Specifies whether a message is to be output if, during import processing, a check reveals that the pubset involved has already been imported on another system or that the last session was terminated abnormally.
SESSION-CHECK-MSG = *YES
If the check reveals that the pubset has already been imported on another system or that the last session was terminated abnormally, message DMS038C is output.
SESSION-CHECK-MSG = *NO
The check is deactivated during an import job for a data pubset; output of message DMS038C is suppressed. System support staff should only use this option, however, if the system was loaded with automatic startup.
RECONSTRUCT-USERCAT = *NO / *RESET / *BY-BACKUP(...)
This operand enables the caller to reconstruct the user catalog, either in full on the basis of a backup copy or from scratch on the basis of the user IDs included in TSOSCAT. The operand is evaluated only in conjunction with the settings ACTUAL-JOIN=*STD/*ZIP; it is ignored with ACTUAL-JOIN=*FIRST.
RECONSTRUCT-USERCAT = *NO
No reconstruction is performed.
RECONSTRUCT-USERCAT = *RESET
The user catalog is reconstructed. The user IDs are taken from the current TSOSCAT. The entries are reset.
RECONSTRUCT-USERCAT = *BY-BACKUP(...)
The user catalog is reconstructed on the basis of a backup user catalog
($TSOS.SYSSRPM.BACKUP) saved earlier with ARCHIVE and restored to the system.
SCOPE = *ALL / BACKUP / *TSOSCAT
These specifications define how to deal with user IDs which are included only in the backup or only in TSOSCAT.
SCOPE = *ALL
All the entries are copied from the backup. Any additional entries included in TSOSCAT are recreated.
SCOPE = BACKUP
The entries in the backup determine which user IDs are set up. Files belonging to user IDs not included in the backup are deleted.
SCOPE = *TSOSCAT
The entries in TSOSCAT determine which user IDs are set up. Only the user IDs which are included in it are copied from the backup or recreated.
RECONSTRUCT-F5-LABEL = *NO / *YES
Specifies whether the reconstruction of the F5 label is to be initiated explicitly.
RECONSTRUCT-F5-LABEL = *NO
Reconstruction of the F5 label is not initiated explicitly. However, the system can initiate a reconstruction internally, regardless of this (e.g. following a system crash). Reconstruction will also take place if a check of the TSOSCAT user chain is requested (operand REPAIR-TSOSCAT=*YES).
RECONSTRUCT-F5-LABEL = *YES
Reconstruction of the F5 label is performed in any case. This covers all volume set belonging to an SM pubset.
DEFECT-VOLUME-SET = *NONE / list-poss(256): <cat-id 1..4>
This operand is only evaluated for SM (System-Managed) pubsets which are imported exclusively or as master. The operand defines which volume sets are defective and are to be removed from the SM pubset. These volume sets are also to be removed from the pubset configuration file and from MRSCAT. The control volume set cannot be removed.
DEFECT-VOLUME-SET = *NONE
All the volume sets listed in the pubset configuration file are imported. If one or more volume sets are found to be defective, the import process aborts. The catalog name of each volume set found to be defective is displayed. The import process must then be repeated, naming all the defective volume sets.
DEFECT-VOLUME-SET = list-poss(256): <cat-id 1..4>
Specifies the catalog names of those volume sets which are no longer to be part of the SM pubset and are to be removed from the pubset configuration file and from MRSCAT. All the files in a defective volume set are removed from the file index of the SM pubset in question and added to a file named $TSOS.SYS.PUBSET.DEFECT.<volset-id>.<date>.<time>, where <date> is in yyyy-mm-dd format and <time> is in hhmmss format. The file names added to this file form the basis for subsequent reconstruction using the HSMS utility.
IN-HOLD-VOLUME-SET = *NONE / list-poss(256): <cat-id 1..4>
This operand is only evaluated for SM (System-Managed) pubsets which are imported exclusively or as master. The operand defines which volume sets are to be placed in the IN-HOLD status when they are imported, i.e. these volume sets are temporarily flagged as not operable. They can be activated again with the MODIFY-PUBSET-RESTRICTIONS command. A volume set that is exported while IN-HOLD, is implicitly reactivated when imported if it was not named explicitly in the IN-HOLD-VOLUME-SET operand.
IN-HOLD-VOLUME-SET = *NONE
None of the volume sets is put IN-HOLD.
IN-HOLD-VOLUME-SET = list-poss(256): <cat-id 1..4>
Specifies the volume sets that are put IN-HOLD while being imported.
REPAIR-TSOSCAT = *NO / *YES
Specifies whether the TSOSCAT user chains are repaired during the CMS start phase of the import.
REPAIR-TSOSCAT = *NO
TSOSCAT user chains are not repaired.
REPAIR-TSOSCAT = *YES
This specification should only be entered if the import was not possible because of a defective TSOSCAT. Catalog entries can be lost when the repair process takes place.
TSOSCAT user chains are analyzed in the CMS start phase of the import, and they are repaired, if necessary. Defective blocks are removed. If a file’s catalog entry was on a defective block, that file is no longer accessible. For further information on the reconstruction of file catalogs, see the “Introduction to System Administration” [14]. An F5 label reconstruction for the entire pubset is performed.
CHECK-PUBSET-MIRRORS = *NO / *YES
Determines whether the homogeneity of the pubset is to be checked. In the case of a pubset which is not mirrored a check is also made to see whether only individual disks are mirrored. A pubset is homogeneous when all volumes of the pubset have the same mirroring properties.
The homogeneity check is performed for the currently supported full replication forms (see the respective manual “SHC-OSD” [37)]).
CHECK-PUBSET-MIRRORS = *NO
No homogeneity check is performed.
CHECK-PUBSET-MIRRORS = *YES
A homogeneity check is performed.
Return codes
(SC2) | SC1 | Maincode | Bedeutung |
|---|---|---|---|
0 | CMD0001 | Command executed without error | |
1 | 0 | DMS0350 | Pubset already available |
1 | CMD0202 | Syntax error | |
32 | DMS0352 | Error while accessing MRSCAT entry | |
64 | DMS0360 | No authorization for command | |
64 | DMS036B | Missing MRSCAT entry, wrong type | |
64 | DMS037B | Import as shared PVS not possible | |
64 | DMS13C9 | Pubset has already been remotely imported; import mode cannot | |
130 | DMS0351 | Other import/export task active | |
130 | DMS035A | Maximum task number reached | |
130 | DMS0362 | Class-4 memory error |
Notes
The home pubset cannot be imported explicitly. The home pubset is imported automatically during system initialization (startup phase).
The IMPORT-PUBSET command generates a new task, the IMPORT task, and starts it. Actual importing is performed by this IMPORT task asynchronously with the calling task. After successful generation of the IMPORT task, the following message is output on the console:
DMS035B IMPORT PUBSET TASK WITH TSN '(&00)' FOR PUBSET WITH PUBSET ID '(&01)' HAS BEEN CREATED AND STARTED.All messages output by the IMPORT job are sent to the console.
Specifications made via
RESIDENT-BUFFERSandNUMBER-OF-BUFFERScan indirectly influence the working set or paging rate of the system. If, for example, a large number of resident buffers are created on a small system, the cataloging operations will be faster but the paging rate for all other applications will increase.If no buffer specifications are made, the system’s default values are used. The following 3-level hierarchy applies:
Explicit parameter specifications in the IMPORT-PUBSET command.
Specifications via the ADD- OR MODIFY-MASTER-CATALOG-ENTRY command.
If only one of the parameters RESIDENT-BUFFERS or NUMBER-OF-BUFFERS is specified, the default value applies to the other one (RESIDENT-BUFFERS= *NO, NUMBER-OF-BUFFERS=32).
Specification via class 2 system parameters CATBUFR and BMTNUM
For reasons of performance and reliability, a minimum number of CMS buffers is defined by the system. If a smaller number is specified explicitly in the NUMBER-OF-BUFFERS operand, the minimum number defined by the system is set.
If the pubset to be imported is still locked due to a previous system crash, the operator can cancel this lock by means of the UNLOCK-DISK command. However, the operator must first ensure that the pubset is not being used by another system which is currently active.
The MRSCAT of the pubset must contain a static definition of how import processing is to react in the event of an error during a new reservation of a cache area (see also the MODIFY-PUBSET-CACHE-ATTRIBUTES command) because the cache area cannot be made available in the required size:
Import processing continues using the remaining buffer available.
Import processing is aborted.
Whenever a new MRSCAT entry is added, the default value, i.e. cancelation in the event of an error, applies.
Notes on importing a volume set with conversion to an SF pubset
The function “import and convert volume set” (see the USE=*EXCLUSIVE(CONVERT-VOLUME-SET=*YES) operand on "IMPORT-PUBSET") is a basic function for the recovery of SM pubsets whose control volume set has failed: converting the remaining intact volume sets into SF pubsets makes the data present on them available again and it is then possible to recover the SM pubset using SMPGEN (see also the “System Managed Storage” User Guide [45]).
The conversion of volume sets results in operable SF pubsets. Consequently, this function should not be used for anything other than the recovery of SM pubsets without very careful consideration. The specific problem of the maximum length of file names will be examined in the following. In all cases, it is necessary to remember that in an SM pubset, the files processed by an application are not necessarily all located in the same volume set. Following the subdivision of an SM pubset into SF pubsets by means of the import/convert function it is therefore no longer possible to address the files belonging to an application uniquely via defcat or a single catalog ID. The corresponding metadata is also no longer available in full.
The procedure described in the chapter “SMPGEN” of the “Utility Routines” User Guide [9] largely applies to the preparation of an SMPGEN run performed in order to recover an
SM pubset. However, the FDDRL backup of the volumes in question should be performed within a recovery scenario before the “conversion import” step in order to ensure that this step is also protected by a physical backup.
When performing conversion, the following points relating to the control volume set, the length of file names, file generations and DAB caches should be considered:
Control volume set
It is not possible to convert control volume sets, and such an operation would also have no point, since the function “import and convert” is used for recovery purposes on the failure of a control volume set. The metadata stored on the failed control volume set must be recovered from a backup or other source following restoration of the SM pubset by SMPGEN.
File name length
On conversion, the catalog ID of the volume set is taken over as the catalog ID of the resulting SF pubset. If the length of this catalog ID is greater than the length of the (previously valid) catalog ID of the SM pubset then it is necessary to ensure that the maximum possible file name length (54 characters) is not exceeded. To this end, when conversion is performed, any files whose names would exceed the maximum permitted length are renamed. A message, which requests operator confirmation, is issued at the console in order to query whether renaming should be performed. The names of the renamed files have the following structure:
:<catid>:$<userid>.S.RENAME.<timestamp>.<tempfile_indicator>.<counter>
The name sections have the following meanings:
<catid> | Catalog ID of the SF pubset |
<userid> | user ID |
<timestamp> | Time stamp in ISO4 format |
<tempfile_indicator> | Displays whether a temporary file is concerned: |
T: temporary file | |
N: "normal" file |
Any file renaming operations that are performed are logged in an ISAM file on the home pubset. The name of the file is:
:<catid_home>:$TSOS.TSOSCAT.CONV.<catid>.<timestamp>
where <catid_home> indicates the catalog ID of the home pubset, <catid> the catalog ID of the SF pubset created as a result of the conversion and <timestamp> the time stamp in ISO4 format.
The log records indicate the allocation of the file names generated during conversion to the original file names. It is particularly important to ensure that file generations which have excessively long file names are also renamed. When they are renamed, they are also assigned the default name as described above and lose the “file generation” property.
Example
The SM pubset K contains a volume set F64K. Following an error in the control volume set, the remaining volume sets, including F64K, are initially converted into SF pubsets. This requires certain files to be renamed. The log file is located on the home pubset A:
:A:$TSOS.TSOSCAT.CONV.F64K.2011-10-05.112950
Contents of the log file:
:F64K:$USER1234.S.RENAME.2011-12-06-090300.N.000002 ,:F64K:$USER1234.FILEA901234567890123456789012345678901234 :F64K:$USER1234.S.RENAME.2011-12-06-090300.N.000004 ,:F64K:$USER1234.FILEGROUP3456789012345678901234567(*0001) :F64K:$USER1234.S.RENAME.2011-12-06-090300.N.000005 ,:F64K:$USER1234.FILEGROUP3456789012345678901234567(*0003) :F64K:$USER1234.S.RENAME.2011-12-06-090300.T.000003 ,:F64K:$USER1234.FILEXXX1234567890123456789012345678901234 :F64K:$USER1234.S.RENAME.2011-12-06-090300.N.000001 ,:F64K:$USER1234.FILE8901234567890123456789012345678901234 'BLANK''BLANK''BLANK''BLANK''BLANK''BLANK''BLANK''BLANK''BLANK''BLANK''BLANK' ,:F64K:$USER1234.FGG1(*0002)
Following restoration of the SM pubset, the renamed files can be given their original names again with the help of the logging file. How to proceed in the case of file generation groups is described in the next paragraph ("File generation groups"). Once recovery has been performed successfully and the original file names have been restored it is essential to delete the log files, after backing them up if necessary. If this is not done, name conflicts may occur when importing and converting volume sets with the same name and, in some cases, may result in faulty operation.
File generation groups
In the case of SM pubsets, the file group’s catalog entry is located on the control volume set while the catalog entries for the individual file generations can be distributed across the volume sets as required. Consequently, after the volume sets have been converted into SF pubsets, the individual file generations and associated catalog entries are present whereas group entries are not. The question of renaming file generations with “excessively long” file names during the conversion process has already been addressed.The names of the remaining file generations are logged without being renamed. When this is done, the log file contains spaces in place of the new file name (see example, "IMPORT-PUBSET").
New catalog entries must be created for the file generation groups before these can be accessed. The following procedure is recommended:
The group entry is created for each corresponding individual generation with the number <n>:
/CREATE-FILE-GROUP <filename>,*GENERATION-PARAMETER(MAXIMUM=1,
FIRST-GENERATION=<n>, LAST-GENERATION=<n>)
The content of the file generation is then copied to a file for which any required file name can be specified. The name of the file generation and the target file are logged. This file generation group is then deleted.
Once the SM pubset has been restored, it is possible to recover the file generation groups: The group entry is recreated. After this, the files that were created during conversion or manually from file generations are again added to the group as file generations by means of the MODIFY-FILE-ATTRIBUTES command. It should be noted that file generations that were stored on the control volume set of the original SM pubset are lost. This may result in discontinuities in the version numbers of the generation. This consideration should be borne in mind when performing the recovery.
DAB caches
When caching is performed with DAB (see also the “DAB” User Guide [5]) it is necessary to distinguish between ADM-PFA caching and (user) PFA caching. In both cases, synchronization with any existing cache data is performed as part of pubset import involving volume set conversion.
ADM-PFA caching
ADM-PFA caching can be set for entire SM or SF pubsets, volume sets or individual files as required. When this is done, DAB uses the volumes in question and the names of the buffered files as the metadata. It is necessary to distinguish between the following three scenarios when an SM pubset’s control volume set fails:Export of the intact volume set is possible and is performed
In this case, the data from the volume sets is written back. Only control volume set data may be present in the cache. In order to prepare for pubset recovery it is necessary to terminate DAB caching for the objects in question using /STOP-DAB-CACHING and also, if the cache contains data belonging to the defective control volume set, /FORCE-STOP-DAB-CACHING. When this is done, a list of the “pinned” files is created.Import with conversion and cache present in the current session
This is the situation that occurs if the cache is not cleared in case a). However, in this situation the cache contains no data. Caching of the data ranges in question is prohibited due to the import/conversion of the volume set. Due to the fact that after import and conversion, the file names administered by DAB no longer correspond to the data present in the pubset, it is essential to clear the cache areas in question with /STOP-DAB-CACHING.
User PFA
In the case of user PFA, a cache area is always assigned to one volume set (for SM pubsets). It will probably not be possible to clear the cache area for the defective control volume set and this will have to be terminated with the /FORCE-DESTROY-CACHE command. In the case of all other volume sets, the assigned cache area is cleared correctly following an export due to a failed control volume set. No new cache area is set up when the volume sets are subsequently imported and converted.
Using the "Import with homogeneity check" function
The homogeneity check with regard to SRDF and/or BCV mirroring for a pubset which is to be imported is executed by specifying the CHECK-PUBSET-MIRRORS = *YES operand.
If in the course of an import a volume is detected which has different mirroring properties from volumes which have already been processed, the answerable message DMS1369 is output on the console. Depending on the operator’s answer, one of the following procedures is selected:
Pubset import is aborted.
Import processing is continued despite the fact that the volume of the pubset which has just been processed has been recognized as inhomogeneous. In this case the message
DMS136Bis issued on the console for every further volume which has different mirroring properties.