Can I add or change the length of my key management fields?
Article ID: 55380
Updated On:
Products
Issue/Introduction
Can I add or change the length of my key management fields?
Environment
Component: ALCMST
Resolution
Yes, but in order to do it successfully, you require 5.3.1 PTF SU02726 which provides:
- variable length format management fields in the ZCL
- conversion utility ZCEMFCNV
After SU02726 is applied, all new ZCL records will be written with management fields in the new variable length format. Records previously existing on the ZCL will continue to have the old fixed format.
Use utility ZCEMFCNV to convert these older ZCL records to the new format. This only needs to be done once per ZCL.
IMPORTANT:
ZCLs must be converted prior to changing the key management field definitions. If key management field definition is changed without converting ZCLs then records with fixed format may not be correctly identified during key searches.
If not changing key management fields definitions, it is not necessary to run this utility. Alchemist has the ability to read and recognize both fixed and variable format records.
ZCEMFCNV ----- Converting Management Fields
ZCEMFCNV updates entries from the ZCL database and converts the management fields from fixed length entries to variable length entries. This allows any given management field to have its length changed without causing problems with the ZCL database. (Note that the limit for the total length of all key fields has not changed nor has the individual maximum length changed.)
Conversion Procedure
Warning: Follow this procedure exactly. Otherwise, irreparable damage may occur on your ZCL database.
Sample JCL to execute this utility can be found in SAMPLIB member CYBALI49.
Example:
Convert database CYB 1. SAL 5310.TEST.ZCL with management fields SR, Defect, PTF:
OUTPUT System-Level Configuration - Management Information Fields. ---------
Command ===> OE-Name: #######
Field Field Title Text Key Mandatory? Numeric Only? Max Value Lth.
====== ================ === ========== ============= ==============
1. SR S NO NO 4
2. DEFECT D NO NO 4
3. PTF P NO NO 4
IMPORTANT: Do not change the System Configuration until Step 10. You may want to start with the smallest ZCL dataset first.
Step 1 -- Shutdown Alchemist.
Step 2 -- Copy the CYB 1. SAL 5310.TEST.ZCL database (e.g. CYB 1. SAL 5310.TEST.ZCL. COPY )
Step 3 -- Rename CYB 1. SAL 5310.TEST.ZCL (e.g. CYB 1. SAL 5310.TEST.ZCL.BKUP)
Step 4 -- Rename the copied ZCL to the production name. (e.g. CYB 1. SAL 5310.TEST.ZCL. COPY to CYB 1. SAL 5310.TEST.ZCL)
Step 5 -- Restart Alchemist. Try to run this utility during a period of low user activity.
Step 6 -- Run ZCEMFCNV against CYB 1. SAL 5310.TEST.ZCL (which is the copied one) in Simulation mode to ensure that it will do what you expect.
Step 7 - Run ZCEMFCNV against CYB 1. SAL 5310.TEST.ZCL(which is the copied one) in Live mode (non-Simulation).
Step 8 -- Verify that the change has taken effect. Run ZCEMFCNV against the ZCL in Simulation mode to ensure that the entities were converted (marked with an ..*..).
Step 9 -- Repeat steps 1 to 8 for all zone ZCL datasets before proceeding to step 10.
Step 10 -- Change the System Configuration to effect the desired change of field size for the candidate management field.
Step 11 -- Re-cycle all Alchemist tasks.
Step 12 -- Retain the original ZCL ( CYB 1. SAL 5310.TEST.ZCL.BKUP) for backup purposes in line with your installation's policies.
Parameters
Supply parameters via the EXEC PARM field
PARM=' keyword = value[,keyword2=value2,...] '
OENAME|OE=oename - Required. Specify the OE of the ZCL to be updated.
Default - none
SIMULATE| SIM ={Y | N} - Optional. The program can be run in simulate mode to see what the results would be without actually altering the ZCL.
Default - SIMULATE=N
TRACE|TR={Y|N} - Optional. Produce additional information useful for tracking down problems.
Default - TRACE=N
DD Statements
ZCL - This is the ZCL database name - prefix.ZCL
SYSPRINT - Utility message output. Note: Long entity names will be truncated to 12 characters in the message output.
Output
Sysprint output - see the examples below.
The ZCL userdata for each entity is updated. (See example under "Conversion Procedure")
Condition Codes
0 - Successful
8 - Failure. See messages on Sysprint or job log
Example 1 --- Converting Test ZCL members
Note: In the examples below, ECO stands for Environment Customization Options
//ZCEMFCNV JOB
//ZCEMFCNV EXEC PGM=ZCEMFCNV,
// PARM=('OENAME=######', OE NAME (OE=)
// 'TRACE=N', TRACE OPTION (TR=)
// 'SIMULATE=N') SIMULATE CHANGE ONLY (SIM=)
//*
//SYSPRINT DD SYSOUT=*
//ZCL DD DISP=SHR,DSN=prefix.TEST.ZCL
//
Output:
ZCEMFC00I - *** ALCHEMIST MANAGEMENT FIELD CONVERSION PROGRAM ***
ZCEMFC01I - EXEC PARMS SUPPLIED:
ZCEMFC02I - OENAME=######,TRACE=N,SIMULATE=N
ZCEMFC03I - EXEC PARMS IN EFFECT:
ZCEMFC04I - SIMULATE=N,TRACE=N,OENAME=######
ZCEMFC13I - ENTITY NAME VERSION KEY/KEY VALUE... (* = ALREADY CONVERTED)
.
.
.
ZCEMFC16I - 56 DIRECTORY RECORDS READ
ZDEMFC17I - 9 RECORDS ALREADY CONVERTED
ZCEMFC19I - 1 CONTROL RECORDS INELIGIBLE FOR CONVERSION
ZCEMFC18I - 46 RECORDS CONVERTED DURING THIS RUN
ZCEMFC20I - LIVE RUN COMPLETE.
Example 2 --- Converting Test ZCL members with Tracing
//ZCEMFCNV JOB
//ZCEMFCNV EXEC PGM=ZCEMFCNV,
// PARM=('OENAME=######', OE NAME (OE=)
// 'TRACE=Y', TRACE OPTION (TR=)
// 'SIMULATE=N') SIMULATE CHANGE ONLY (SIM=)
//*
//SYSPRINT DD SYSOUT=*
//ZCL DD DISP=SHR,DSN=prefix.TEST.ZCL
//
Output:
ZCEMFC00I - *** ALCHEMIST MANAGEMENT FIELD CONVERSION PROGRAM ***
ZCEMFC01I - EXEC PARMS SUPPLIED:
ZCEMFC02I - OENAME=######,TRACE=Y
ZCEMFC03I - EXEC PARMS IN EFFECT:
ZCEMFC04I - SIMULATE=N,TRACE=Y,OENAME=######
ZCEMFC95I - CONTACTING REQUEST MANAGER FOR OE #######
ZCEMFC94I - REQUEST MANAGER CONTACTED
ZCEMFC92I - *** ECO DEFINITIONS ***
ZCEMFC91I - TITLE KEY MAN NUM LEN OFF
ZCEMFC93I - SR S N Y 04 00
ZCEMFC93I - DEFECT D N Y 04 02
ZCEMFC93I - PTF P N Y 04 04
ZCEMFC93I - AUTHOR A N N 14 06
ZCEMFC93I - N N 00 20
ZCEMFC93I - N N 00 20
ZCEMFC93I - N N 00 20
ZCEMFC93I - N N 00 20
ZCEMFC97I - OPENING ZCL DB
ZCEMFC96I - ZCL DB OPENED
ZCEMFC13I - ENTITY NAME VERSION KEY/KEY VALUE... (* = ALREADY CONVERTED)
ZCEMFC16I - 3 DIRECTORY RECORDS READ
ZDEMFC17I - 0 RECORDS ALREADY CONVERTED
ZCEMFC19I - 1 CONTROL RECORDS INELIGIBLE FOR CONVERSION
ZCEMFC18I - 2 RECORDS CONVERTED DURING THIS RUN
ZCEMFC20I - LIVE RUN COMPLETE.
Example 3 --- Converting Test ZCL members with Tracing and Simulation
//ZCEMFCNV JOB
//ZCEMFCNV EXEC PGM=ZCEMFCNV,
// PARM=('OENAME=######', OE NAME (OE=)
// 'TRACE=Y', TRACE OPTION (TR=)
// 'SIMULATE=Y') SIMULATE CHANGE ONLY (SIM=)
//*
//SYSPRINT DD SYSOUT=*
//ZCL DD DISP=SHR,DSN=prefix.TEST.ZCL
//
Output:
ZCEMFC00I - *** ALCHEMIST MANAGEMENT FIELD CONVERSION PROGRAM ***
ZCEMFC01I - EXEC PARMS SUPPLIED:
ZCEMFC02I - OENAME=######,TRACE=Y
ZCEMFC03I - EXEC PARMS IN EFFECT:
ZCEMFC04I - SIMULATE=Y,TRACE=Y,OENAME=######
ZCEMFC95I - CONTACTING REQUEST MANAGER FOR OE ######
ZCEMFC94I - REQUEST MANAGER CONTACTED
ZCEMFC92I - *** ECO DEFINITIONS ***
ZCEMFC91I - TITLE KEY MAN NUM LEN OFF
ZCEMFC93I - SR S N Y 04 00
ZCEMFC93I - DEFECT D N Y 04 02
ZCEMFC93I - PTF P N Y 04 04
ZCEMFC93I - AUTHOR A N N 14 06
ZCEMFC93I - N N 00 20
ZCEMFC93I - N N 00 20
ZCEMFC93I - N N 00 20
ZCEMFC93I - N N 00 20
ZCEMFC97I - OPENING ZCL DB
ZCEMFC96I - ZCL DB OPENED
ZCEMFC13I - ENTITY NAME VERSION KEY/KEY VALUE... (* = ALREADY CONVERTED)
ZCEMFC16I - 3 DIRECTORY RECORDS READ
ZDEMFC17I - 0 RECORDS ALREADY CONVERTED
ZCEMFC19I - 1 CONTROL RECORDS INELIGIBLE FOR CONVERSION
ZCEMFC18I - 2 RECORDS CONVERTED DURING THIS RUN
ZCEMFC21I - SIMULATION RUN COMPLETE (NO RECORDS WRITTEN).
Example 4 --- Accidentally rerunning ZCEMFCNV against the same ZCL
Output: ZCEMFC00I - *** ALCHEMIST MANAGEMENT FIELD CONVERSION PROGRAM *** ZCEMFC01I - EXEC PARMS SUPPLIED: ZCEMFC02I - OENAME=######,TRACE=Y ZCEMFC03I - EXEC PARMS IN EFFECT: ZCEMFC04I - SIMULATE=N,TRACE=Y,OENAME=###### ZCEMFC95I - CONTACTING REQUEST MANAGER FOR OE ###### ZCEMFC94I - REQUEST MANAGER CONTACTED ZCEMFC92I - *** ECO DEFINITIONS *** ZCEMFC91I - TITLE KEY MAN NUM LEN OFF ZCEMFC93I - SR S N Y 04 00 ZCEMFC93I - DEFECT D N Y 04 02 ZCEMFC93I - PTF P N Y 04 04 ZCEMFC93I - AUTHOR A N N 14 06 ZCEMFC93I - N N 00 20 ZCEMFC93I - N N 00 20 ZCEMFC93I - N N 00 20 ZCEMFC93I - N N 00 20 ZCEMFC97I - OPENING ZCL DB ZCEMFC96I - ZCL DB OPENED ZCEMFC13I - ENTITY NAME VERSION KEY/KEY VALUE... (* = ALREADY CONVERTED) ZCEMFC16I - 3 DIRECTORY RECORDS READ ZDEMFC17I - 2 RECORDS ALREADY CONVERTED ZCEMFC19I - 1 CONTROL RECORDS INELIGIBLE FOR CONVERSION ZCEMFC18I - 0 RECORDS CONVERTED DURING THIS RUN ZCEMFC20I - LIVE RUN COMPLETE.
Other Relevant Information:
See SAMPLIB member CYBALI49 for sample JCL to execute this utility.
ISPF Panel ZDDSC02A is updated as part of PTF SU02726. Take the necessary steps to implement this panel into your environment.
Feedback
