Can I add or change the length of my key management fields?

Document ID : KB000055380
Last Modified Date : 14/02/2018
Show Technical Document Details

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: AS5311
                                                                               
  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=ALCOEN', 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=ALCWMT,TRACE=N,SIMULATE=N
ZCEMFC03I - EXEC PARMS IN EFFECT:
ZCEMFC04I - SIMULATE=N,TRACE=N,OENAME=ALCWMT
ZCEMFC13I - ENTITY NAME VERSION KEY/KEY VALUE... (* = ALREADY CONVERTED)
ZCEMFC14I - AMGIN0 0000073 *S/S111 D/D222 P/ 48 I/ 87654321 Y/ 60724
ZCEMFC14I - AMGIN2 0000070 *S/SSSS D/210657972 P/PPPP A/MI
ZCEMFC14I - AMGIN3 0000071 *S/SSSS D/210657972 P/PPPP A/AU
ZCEMFC14I - AMGIN4 0000072 *S/S111 D/D222 P/P333
ZCEMFC14I - J4 0000069 *S/STUVWXYZ D/ 12345678 P/PQRSTU A/AB
ZCEMFC14I - AIEFBR14 0000022 S/ D/ P/ 64 I/ 77952576 Y/ 421075
ZCEMFC14I - AMGIN 0000056 S/S111 D/D222 P/ 21 I/ 2116288 Y/ 421075
.
.
.
ZCEMFC14I - XLM5 0000018 S/ D/ P/ 64 I/ 77952576 Y/ 421075
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=ALCOEN', 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=ALCOEN,TRACE=Y
ZCEMFC03I - EXEC PARMS IN EFFECT:
ZCEMFC04I - SIMULATE=N,TRACE=Y,OENAME=ALCOEN
ZCEMFC95I - CONTACTING REQUEST MANAGER FOR OE ALCWMT
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)
ZCEMFC14I - AMGIN2 0000070 S/SSSS D/210657972 P/PPPP A/MI
ZCEMFC14I - AMGIN3 0000071 S/SSSS D/210657972 P/PPPP A/AU
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=ALCOEN', 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=ALCOEN,TRACE=Y
ZCEMFC03I - EXEC PARMS IN EFFECT:
ZCEMFC04I - SIMULATE=Y,TRACE=Y,OENAME=ALCOEN
ZCEMFC95I - CONTACTING REQUEST MANAGER FOR OE ALCWMT
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)
ZCEMFC14I - AMGIN2 0000070 S/SSSS D/210657972 P/PPPP A/MI
ZCEMFC14I - AMGIN3 0000071 S/SSSS D/210657972 P/PPPP A/AU
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=ALCOEN,TRACE=Y
ZCEMFC03I - EXEC PARMS IN EFFECT:
ZCEMFC04I - SIMULATE=N,TRACE=Y,OENAME=ALCOEN
ZCEMFC95I - CONTACTING REQUEST MANAGER FOR OE ALCWMT
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)
ZCEMFC14I - AMGIN2 0000070 *S/SSSS D/210657972 P/PPPP A/MI
ZCEMFC14I - AMGIN3 0000071 *S/SSSS D/210657972 P/PPPP A/AU
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.