Category: Z/OS

Using z/OS health checker is good – but how do I use it?

I had a message on the console saying

HZS0001I CHECK(IBMICSF,ICSF_CLEAR_KEYS): CSFH0056E Clear keys in the CKDS, PKDS, or TKDS were found.

Great – but what next?

In SDSF, you can use the CK command to display the health-checker events.

There were a lot of checks. The SDSF command CK E, displays only those with exceptions; where the result was > 0.

There are various line commands, but SE gives you all of the information, in the ISPF editor.

In the page it told me

CSFH0054I Check for clear keys in the CKDS, PKDS, and TKDS. 
Active TKDS: COLIN.SCSFTKDS 
-----------------------------------------------------
PKISRVD.PKITOKEN                00000001T
Explanation: ...
System Action:  ...                           
Operator Response: ...
System Programmer Response: ...

Great – this is very useful. However the action “Contact the ICSF administrator” is not very helpful as I am the ICSF administrator!

Migrating an ADCD z/OS release: user data sets, user catalogs and High Level Qualifier

Start here:Migrating an ADCD z/OS release to the next release.

I have covered datasets, aliases and catalogs in One minute mvs: catalogs and datasets.

If your master catalog is a mess

If you have your personal data sets in the master catalog instead of a user catalog, see Here’s another nice mess I’ve gotten into!

You could start again on the new system and do it properly.

Note down which volumes your data sets are on. On the new system define a user catalog and alias, and use ISPF 3.4, to list the contents of the volume and use the C local command to catalog the data set.

I found the easiest way of doing VSAM datasets is a backup and restore

If you have a user catalog for your user data sets

You need to get a list of the user aliases in the master catalog on the old system, and the user catalogs the aliases refer to, before trying to import them into the new system. I could not find a way to list the master catalog from another system. See here for example JCL

To access your data sets in a user catalog you need to import the catalog into the master catalog on the new system, and define the aliases for your data to the catalog.

On your new system, you will not have immediate access to your data sets, so you either need

  • to access a dataset, and specify the volser information,
  • or you need to have a copy of the JCL to import a user catalog, and define alias, stored in a note pad area outside of z/OS. Edit a member such as USER.*.PROCLIB(TEMP) and paste the import catalog JCL. When that has worked, paste in the add alias to your datasets ( COLIN.*). Once you have done this, you can use ISPF 3.4 and use COLIN.* to locate your data sets.

Once you have your list of aliases and user catalogs, you can IPL the new system and import the user catalogs, and define the aliases.

Product data sets

There is usually an alias in the master catalog for a program product. The alias may have the product release as part of the name. If you have customised any of the product owned datasets, you may need to copy the data off.

Migrating an ADCD z/OS release: ZFS files.

Start here:Migrating an ADCD z/OS release to the next release.

For background see Should I use tar or pax to backup my Unix files?

System files

If you have done any configuration to products which use Unix services, you are likely to have changed files in the file system. For example /etc/syslog.conf.

Configuration files

Many configuration files are configured in the /etc directory.

If you want to find which files have been changed since you have been using the system you could use the ls -ltr command to display the files in each directory, displayed with the latest changed date at the bottom.

This gets very tedious when you have a lot of directories to example. However you can ask Unix to list all files which match a critera, such as changed in the last n days, or newer than an existing file.

Create a file of the comparison data

touch -t 202202211456 /tmp/foo

This creates a file /tmp/foo with the given date year 2022 month 02 date 21 time 1456

find . -type f -newer /tmp/foo |xargs ls -ltr > aa

This is two commands.

  • The find command
    • looks in the current directory (.) and subdirectories
    • for objects with type of files (rather than directories etc)
    • which have been changed more recently than /tmp/foo.
  • The file name is passed to the ls -ltr command to display the date time information.
-rwx------   1 OMVSKERN OMVSGRP       32 Feb 13  2023 ./cssmtp.env 
-rw-r--r--   1 OMVSKERN OMVSGRP     3453 Feb 13  2023 ./mail/ezatmail.cf 
-rwxr-xr-x   1 OMVSKERN OMVSGRP      250 Feb 28  2023 ./hosts 
-rw-r--r--   1 OMVSKERN OMVSGRP   226441 Jun 16  2023 ./pkiserv/pkiserv.tmpl.old 
-rw-r--r--   1 OMVSKERN OMVSGRP    22406 Jun 16  2023 ./pkiserv/pkiserv.conf.old 
...

if you use

find . -type f -newer /tmp/foo |tar -cvf ~/etc.tar –

it will create a tar file containing the changed files. You can then transport the etc.tar file to the newer system and untar it.

You can use the pax command to package the files

find . -type f -newer /tmp/foo |pax -W “seqparms=’space=(cyl,(10,10))'” -o saveext -wzvf “//’COLIN.PAX.TEST'” -x os390

to save the files in pax format into the data set COLIN.PAX.TEST. If the high level qualifier has been defined as an alias is the master catalog on both systems, the data set will be visible on both systems.

Note: If you specify

find . -type d -newer /tmp/foo

It displays all directory entries which have been changed, and displays all the files within those directories.

For example 

total 1344 
-rw-r--r--   1 OMVSKERN OMVSGRP     3252 May  7  2019 ssh_config 
-rw-r--r--   1 OMVSKERN OMVSGRP   553761 May  7  2019 moduli 
-rwx------   1 OMVSKERN OMVSGRP       65 Oct 29  2019 sshd.sh

For example the sshd directory was changed in September this year, so all the files below it are listed. 

Application output files

These are usually in the /var sub-directory. You may not need to move these files across.

User data

You will have your own data in the Unix file systems. If you put the data under the /u file system it should be easy to find! 

You may have configured userids so their home directory is on a “user” ZFS file system, or your home directory could be mixed in with the systems files. For example the file system for IBMUSER is on an ADCD file system (D5USS2).

IBMUSER:/S0W1/etc: >df -P ~                                                         
Filesystem          512-blocks        Used  Available  Capacity Mounted on          
ZFS.USERS              2880000     1277970    1602030       45% /u

The newer system also has a ZFS.USERS. You cannot have both old and new ZFS.USERS mounted at the same time, as the mount takes cataloged data set.

For my application data

IBMUSER:/S0W1/etc: >df -P /u/tmp
Filesystem 512-blocks Used Available Capacity Mounted on
COLIN.ZFS2 2817120 788338 2028782 28% /u/tmp

I can take this ZFS system and mount it on the newer system.

You can tar up the files under a directory and move the tar file to the new system, or you can use pax which I think is better, as it creates a dataset out of the ZFS files.

Using tar

Note: if you use an absolute path in the tar command, when you untar the data it will use the same directory- – which may overrwrite data you wanted to keep.

If you use are relative directory, the data is untarred relative to the current directory.

cd /u/colin
tar -cvf ~/relative.tar *

is better than

tar -cvf ~/absolute.tar /u/colin

On the new system if I use

mk dir oldcolin
cd oldcolin
tar -xtvf relative.tar

it will restore the files in oldcolin.

If I use

mk dir oldcolin
cd oldcolin
tar -xtvf absolute.tar *

it will restore the files to /u/colin – and overwrite any files which were there.

What directories were created?

You can use the command

find /u -type d -newer /tmp/foo |xargs ls -ltrd> aa

to display the directories created/modified since the time of the /tmp/foo file.

This gives output like

drwxrwxrwx  10 OMVSKERN SYS1        8192 Dec  8 13:04 ./adcd 
drwxr-xr-x   2 OMVSKERN 1000        8192 Mar 15  2023 ./tmp/oemput 
drwxrwxrwx   2 OMVSKERN WEBGRP      8192 Apr 25  2023 ./mqweb3/logs 
drwxr-xr-x   2 OMVSKERN SYS1        8192 Jun 16  2023 ./mqweb2/oldconf

You can use the pax -E option to display the contents and extended attributes.

pax -E -f "//'COLIN.PAX.HTTP2'"

Notes the double / and both sets of quotes.

To unpax the files on the new system, cd into the directory and use

pax -k -rvf  "//'COLIN.PAX.TEST'" .

The

  • -k means do not overwrite
  • -r read
  • -v display the details
  • -f from the following file
  • into . (the current directory)

To mount a ZFS on the system

You can have an entry in an BPXPRMxx parmlib member, so a ZFS is mounted at IPL time.

You can also use a TSO command, or a batch job to mount a ZFS

//IBMMFAMO JOB 1,MSGCLASS=H
//MOUNT EXEC PGM=IKJEFT1A
//SYSTSPRT DD SYSOUT=*
//SYSTSIN DD *
MOUNT FILESYSTEM('AZF220.ZFS') TYPE(ZFS) +
MOUNTPOINT('/u/mfa') +
MODE(RDWR) PARM('AGGRGROW') AUTOMOVE

Sharing File systems

You can display the mounted file systems using the D OMVS,F command

This gives output like

ZFS            16 ACTIVE                      RDWR  01/15/2024  L=30  
  NAME=ZFS.USERS                                    14.38.54    Q=0   
  PATH=/u                                                             
  OWNER=S0W1     AUTOMOVE=N CLIENT=N
ZFS            37 ACTIVE                      RDWR  01/15/2024  L=48   
  NAME=COLIN.ZFS2                                   14.38.56    Q=0    
  PATH=/u/tmp                                                          
  OWNER=S0W1     AUTOMOVE=Y CLIENT=N

This shows there are two ZFS file systems, both mounted read/write. The first has

  • data set name ZFS.USERS. On the z24C system – this is the z24C file system. You cannot mount both the z24C, and the z25D file systems at the same time, because the mount command uses the cataloged data set.
  • mounted as path /u

The second has

  • data set name COLIN.ZFS2
  • mounted as path /u/tmp

You can choose to mount your data under an existing path, or create a new tree such as “/my”.

How do I diff on Z/OS with Unix files and directories

I wanted to compare the contents of two directories in Unix System Services on z/OS before I merged them. This took me some time to do because the documented is lacking.

With ISPF you can use SUPERC (3.13), give it two PDSs and it shows you the differences.

On Unix there is the diff command. This can compare individual files, or directories. It can display just the changes, or the changes in context.

File a

AOnly 
line1 
Aline2 
line3

File b

line1 
Bline2 
line3 
BOnly 
BOnly2

Using ispf edit compare to show differences

You can use diff to show the differences in two files, but it is not easy to understand. ISPF EDIT has the compare facility. If you know two files are different you can use

  • oedit /etc/zexpl/rseapi.env
  • use the primary command compare
    • enter the fully qualified name /u/ibmuser/zexpl/rseapi.env,, in the “Name . . . . .” field. if you specify +/filename the + means the same directory.
    • press pf3 and it will show the differences

Because I tend to remove comments to make it easier to see the content, I tend to use

  • oview /etc/ssh/sshd_config you get into ISPF edit, but no changes are saved.
  • Comments start with a #. x all;f ‘#’ all 1 1; f ‘ ‘ 1 1 all;del all nx removes comment lines and blank lines
  • reset to show the hidden lines
  • compare I then specify my version of the file, and see the changes.

  • Lines like ====== TrustedUserCAKeys /etc/ssh/user_ca_key.pub are from my copy.
  • Lines in green with a line number are in both files 000006 Subsystem sftp /usr/lib/ssh/sftp-server
  • Lines like .OAAAA UseDNS yes are from the base file

Update your version, make a copy of the original, then replace the original with your version.

diff -c1 a b – show the files and the changes in context

The line prefix for input file going to output file

  • – to be removed
  • ! to be changed
  • + to be added

The command diff -c1 a b gives

*** a Tue Aug 27 02:48:56 2024              
--- b Tue Aug 27 02:50:41 2024              
***************                             
*** 1,4 ****                                
- AOnly                                     
  line1                                     
! Aline2                                    
  line3                                     
--- 1,5 ----                                
  line1                                     
! Bline2                                    
  line3                                     
+ BOnly                                     
+ BOnly2
  • *** a Tue Aug 27 02:48:56 2024 the first file name, and last changed date
  • — b Tue Aug 27 02:50:41 2024 the second file name, and last changed date
  • *** 1,4 **** the*** show it is file 1, lines 1 to 4
  • – AOnly this line is in file a is not in file b, so would need to be removed(-) from file a
  • ! Aline2 this line is in file b – but different
  • — 1,5 —- this is file b, lines 1 to 5
  • ! Bline2 this line is also in file a – but different
  • + BOnly this line is in file b and and was additional(+) to file a

When one file exists but is empty you get output like

*** /etc/resolv.conf Wed Mar  6 11:54:50 2024                         
--- /u/ibmuser/temp/resolv.conf Thu Dec  7 05:40:24 2023              
***************                                                       
*** 0 ****                                                            
--- 1,2 ----                                                          
+ nameserver 127.0.0.1                                                
+ TCPIPJOBNAME  TCPIP

which follows the rules I explained above. *** 0 **** shows the content after line 0 is empty, because the next line is — 1,2 —- from the other file.

diff a b – show just the changes

gives

1d0             
< AOnly    
3c2             
< Aline2        
---             
> Bline2      
4a4,5           
> BOnly         
> BOnly2

The output can be split into sections. The first line of each section is like

  • 1d0 the first line of a needs to be deleted from b, line 0
  • 3c2 line 3 of a is changed from line 2 of b
  • 4a4,5 lines 4,5 of b need to be added to a

The < and > tell you which file the data came from

When data is changed it gives the lines

  • < content of file a
  • — output divider
  • > content of file b

When the data is in file a and not file b

  • < contents of file a

When the data is in file b and not file a

  • > contents of file b

diff -s dir1 dir2 compare the directory contents

If you specify -s, or just specify two directories, it compares the directory content.

You can use

diff -c1 dir1 dir2

the -c1 to display the contents (how I like it).

With the directory entries you get records like

Only in /u/ibmuser/temp: test.tar 
Common subdirectories: /etc/wbem and /u/ibmuser/temp/wbem           
Only in /etc: yylex.c 
diff -c1 /etc/hosts /u/ibmuser/temp/hosts 
*** /etc/hosts Wed Mar  6 11:06:55 2024 
--- /u/ibmuser/temp/hosts Tue Feb 28 12:43:07 2023

You can find which files are missing from /etc , by using grep ‘Only in /u/ibmuser/temp’ on the output.

It shows the command used for the individual files, and the output

diff -c1 /etc/hosts /u/ibmuser/temp/hosts
*** /etc/hosts Wed Mar  6 11:06:55 2024 
--- /u/ibmuser/temp/hosts Tue Feb 28 12:43:07 2023
...

diff -s -r dir1 dir2 compare the directory contents

The -r option displays the data recursively.

How do I change all members of a PDS? Easy – use an edit macro

I looked on the internet, to find something that would allow me to make the same change to all members of a PDS, and there seemed to be several options, IPOUPDTE, CPPUPDTE, PDSUPDTE, written in assembler many years ago.

I had written an equivalent program in C, but I no longer have the source. I found it as quick to write a solution using Rexx and an ISPF edit, than to find a solution on the internet. The solution is much more flexible, and can do so much more.

The processing has two stages

  • Code to iterate over each member of the PDS, and invoke ISPF EDIT on each member
  • An edit macro to make the changes.

Code to iterate over each member

ISPF 3.4 DSLIST displays data sets

DSLIST - Data Sets Matching COLIN.J*       
Command ===>                               
                                           
Command - Enter "/" to select action       
-------------------------------------------
AA       COLIN.JCL                         
         COLIN.JCL.DCOLLECT.OUTPUT

You can enter local commands at the front of each line. The commands can be ISPF special (D for Delete, C for Catalog, R for Rename), or TSO commands, where a TSO command can be a Rexx exec in the ISPEXEC concatenation. (You can use the TSO ISRDDN command to display the data sets allocated to your session)

I have a Rexx exec called AA.

Access the parameters passed to the rexx

/* rexx */                                           
 ADDRESS ISPEXEC "VGET (ZDLDSN) SHARED"              
 ADDRESS ISPEXEC "VGET (ZDLCMD) SHARED"              
 ADDRESS ISPEXEC "VGET (ZDLLCMD) SHARED"             
 say  "ZDLDSN   " ZDLDSN                             
 say  "ZDLCMD   " ZDLCMD                             
 say  "ZDLLCMD  " ZDLLCMD

With the line command

Command - Enter "/" to select action  
--------------------------------------
AA 99    COLIN.JCL

The Rexx produces

ZDLDSN    COLIN.JCL
ZDLCMD    AA 99
ZDLLCMD   AA 99 'COLIN.JCL'
  • ZDLDSN is the data set name
  • ZDLCMD is the line command and any data
  • ZDLLCMD is the (Long) combined command and the data set

With the line command

aa 99 / Zyx

The dataset name is substituted for /, and the output is 

ZDLDSN    COLIN.JCL
ZDLCMD    AA 99 / Z
ZDLLCMD   AA 99 'COLIN.JCL' Zyx

This means you can pass parameters to your Rexx.

Process every member

The data set name is in variable ZDLDSN. When you use it, you should quote it because your userid may/may not have prefix on, which puts your userid on the front of every data set you use. Without quotes, it could not find dataset COLIN.COLIN.JCL

  • The LMINIT command returns a handle in the DATAID(handle) variable, to refer to the data set. My handle is called data1.
  • The LMOPEN command opens the dataset associated with the handle.
  • The LMMLIST command iterates through the list, starting with a blank member name which indicates start with the first.
  • The EDIT command invokes ISPF edit on the member, and passes the name of an ISPF EDIT macro to use. In my case the macro is called FOREACH.
Address ispexec "LMINIT DATAID(data1) dataset('"ZDLDSN"')" 
if rc <> 0 then 
do /* report the errors */
   say ZERRSM  ZERRLM 
   return 8 
end 
Address ispexec 'LMOPEN DATAID('data1') OPTION(INPUT)' 
member = ' ' 
lmrc = 0 
/*********************************************************************/ 
/* Loop through all members in the PDS, issuing the EDIT service for */ 
/* each.                                                             */ 
/*********************************************************************/ 
Do i = 1 by 1
  Address ispexec 'LMMLIST DATAID('data1') OPTION(LIST), 
   MEMBER(MEMBER) STATS(NO)' 
  If rc =  8 then leave  /* not found */
  If rc <> 0   Then 
  do 
   say ZERRSM  ZERRLM 
   leave 
  end 
  else 
  do 
    Address ispexec 'EDIT DATAID('data1') MEMBER('member') 
     MACRO(FOREACH)' 
  end 
End 
/*********************************************************************/ 
/* Free the member list and close the dataid for the PDS. */ 
/*********************************************************************/ 
Address ispexec 'LMMLIST DATAID('data1') OPTION(FREE)' 
Address ispexec 'LMCLOSE DATAID('data1')' 
Exit 0

From the information passed to the Rexx exec, you could pass the edit macro as a parameter, such as 

AA / MYMAC

I was just lazy and hard coded the macro name.

An edit macro to make the changes

My basic macro just reports the member name, and the size of the file

ADDRESS ISPEXEC 'ISREDIT MACRO' 
"ISREDIT    (last) = LINENUM .ZLAST" 
"ISREDIT    (member ) = MEMBER" 
"ISREDIT    (curr,orig,concat)= DATASET" 
say "foreach " member last curr 
"ISREDIT    END"
  • The LINENUM command returns the line number of the specified line. You can create your own line labels. ISPF provides .ZFIRST and .ZLAST .ZCSR (the line where the cursor is currently.
  • The MEMBER command returns the member name
  • The DATASET command returns the current name of the dataset (and other information)

You can now do conditional processing, if the data set name starts with… then change…; if the member name starts with… then change…

You can use standard ISPF commands for example

/* */ 
/* trace e */ 
ADDRESS ISPEXEC 'ISREDIT MACRO' 

"ISREDIT   X ALL " 
"ISREDIT   FIND '//' ALL" 
"ISREDIT   CHANGE 'IBMUSER' 'COLIN' 1 10 ALL NX" 
return 
"ISREDIT    END"

Without the return statement in the code, the code makes the changes and exits, it invisibly edits all of the members. With the return statement this gives you the opportunity to review the changes and to use end or cancel to leave the edit session.

Whoops – what happened there

To test the macros I use ‘view’ of the member, to edit it, but not save any changes. I then executed the macro.
I was trying to change a VOLSER to a symbol. 

/* */ 
ADDRESS ISPEXEC 'ISREDIT MACRO' 
"ISREDIT    (member ) = MEMBER" 
say member 
"ISREDIT    SCAN OFF" 
if substr(member,1,6) <> "IEASYM" then 
do 
  "ISREDIT   CHANGE 'A3PRD1' '&&SYSP1.' ALL " 
  "ISREDIT   CHANGE 'A3PRD2' '&&SYSP2.' ALL " 
  "ISREDIT   CHANGE 'A3PRD3' '&&SYSP3.' ALL " 
  "ISREDIT   CHANGE 'A3PRD4' '&&SYSP4.' ALL " 
  "ISREDIT   CHANGE 'A3PRD5' '&&SYSP5.' ALL " 
  "ISREDIT   CHANGE 'A3RES2' '&&SYSR2.' ALL " 
  "ISREDIT   CHANGE 'A3SYS1' '&&SYSS1.' ALL " 
  "ISREDIT   CHANGE 'A3CFG1' '&&SYSC1.' ALL " 
end 
return 
"ISREDIT    END"f

I wanted to change A3PRD1 to the symbol &SYSP1. I had use use &&, and SCAN OFF. Without these, ISPF treats &SYSP1 as an ISPF symbol, cannot find it, so replaces it with a null.

How do I compare two PDS on z/OS

I am migrating from one ADCD system to a newer version. I wanted to see the differences in the supplied members.

In ISPF 3.13 (SUPERCE) you can compare dataset members.

  • Enter the New DS Name and the Old DS Name
  • If you leave the PDS Member List blank, you get prompted on the next page to select the members of interest. I specified *
  • Compare type 1 (file) gives you a report on the members which are the same or not. See Output from file compare
  • Compare type 2 (line) shows the contents which are different.
    • Listing type 2 (Delta) gives just the changed lines. See here
    • Listing type 3 (CHNG) shows the change in context. See here
    • Listing type 4 (Long) shows the all the members

Output from file compare

                                                                                     
                      MEMBER SUMMARY LISTING (FILE COMPARE) 
                                                                                     
DIFF SAME    MEMBERS-COMPARED  N-BYTES O-BYTES N-LINES O-LINES N-HASH-SUM O-HASH-SUM 
                                                                                     
      **     IEASYMCP              400     400       5       5  0EA58F29   0EA58F29 
      **     IEASYMZZ             2000    2000      25      25  2D0DCCA3   2D0DCCA3 
 **          IEASYSCP              800     720      10       9  6D0F7302   737B66E5 
      **     IEASYSC2              800     800      10      10  7B933738   7B933738 
      **     IEASYS00             3760    3760      47      47  61EAEE95   61EAEE95 
      **     IGDSMS00             1920    1920      24      24  A24BDDC8   A24BDDC8 
      **     IKJTSO00             9920    9920     124     124  46049FE2   46049FE2

Output from Line compare, CHNG output(3)

This shows the changes in context.

  • At the front of the line is I or D, to show what was added or deleted
  • The TYPE MAT= is the count of matching lines, and the line numbers within the files.
  • TYPE=RPL is the count of lines replace, and the line numbers within the files.
 NEW: USER.Z31A.PARMLIB(IRRPRMCP)     OLD: USER.Z25D.PARMLIB(IRRPRMCP) 
                                                                                                            
                      LISTING OUTPUT SECTION (LINE COMPARE) 
                                                                                                            
 ID       SOURCE LINES                                TYPE  LEN N-LN# O-LN# 
     ----+----1----+----2----+----3----+----4----+----... 
     DATABASE_OPTIONS                                 MAT=    3 00001 00001 
       DATASETNAMETABLE                                         00002 00002 
          ENTRY                                                 00003 00003 
 I -          PRIMARYDSN(COLIN.RACFDB.NEW)            RPL=    1 00004 00004 
 D -          PRIMARYDSN(COLIN.RACFDB2) 
              BACKUPDSN(SYS1.RACFDS.BACKUP)           MAT=    1 00005 00005

You also get the output from the Output from file compare

Output from Line compare, Delta output(2)

This just gives the inserted and deleted lines. It is a subset of the data above.

NEW: USER.Z31A.PARMLIB(IRRPRMCP)  OLD: USER.Z25D.PARMLIB(IRRPRMCP) 
                                                                                                            
                     LISTING OUTPUT SECTION (LINE COMPARE) 
                                                                                                            
ID       SOURCE LINES                              TYPE  LEN N-LN# O-LN# 
    ----+----1----+----2----+----3----+----4----+--... 
                                                   MAT=    3 
I -          PRIMARYDSN(COLIN.RACFDB.NEW)          RPL=    1 00004 00004 
D -          PRIMARYDSN(COLIN.RACFDB2)

You also get the output from the Output from file compare.

z/OS systems-ssl strange behaviour with environment variables

I was trying to use system ssl to write a program to use native z/O TLS facilities. I wasted a couple of hours because it said it could not find my keyring. Then when I collected a trace, it sometimes did not find the file – which did exist as I could list it.

If I used

//START1   EXEC PGM=GSKMAIN,REGION=0M, 
//*  PARM='4000' 
// PARM=('ENVAR("_CEE_ENVFILE=DD:STDENV")/4000') 
//STDENV DD PATH='/u/ibmuser/gskparms'

When the USS file had

GSK_TRACE_FILE=/tmp/zzztrace.file 
GSK_TRACE=0xff 
GSK_KEYRING_FILE=START1/TN3270

This worked file

When I used

//START1   EXEC PGM=GSKMAIN,REGION=0M, 
//*  PARM='4000' 
// PARM=('ENVAR("_CEE_ENVFILE=DD:STDENV")/4000') 
//STDENV  DD * 
GSK_TRACE_FILE=/tmp/zzztrace.file 
GSK_TRACE=0xff 
GSK_KEYRING_FILE=START1/TN3270 
/*

This failed to work.

If I looked in the trace file I had

ENTRY gsk_open_keyring(): ---> Keyring 'START1/TN3270                       '

Where it had taken the whole length of the line – and so START1/TN3270 padded with blanks was not found.

The trace file was not /tmp/zzztrace.file, it was /tmp/zzztrace.file padded with lots of blanks!

The answer is to use a environment file in USS, not in JCL or a data set.

One minute mvs: catalogs and datasets.

In days of old, when 64KB was a lot of real storage, to reference a data set you had to specify the data set name and the DASD volume the data set was on. DSN=MY.JCL,VOL=SER=USER00

After this, the idea of a catalog was developed. Just like the catalog in a library, it told you where things were stored. When you created a data set, and specified DISP=(NEW,CATLG), the data set name and volume were stored in the catalog. When you wanted to use a data set, and did not specify the volume, then the catalog was used to find the volume for the data set.

As systems grew and the number of data sets grew, the catalog grew and quickly became difficult to manage. For example if you deleted data sets, the entry was logically removed from the catalog, resulting in gaps in the catalog.

After this a multi level catalog was developed. You have one master catalog. You can have many user catalogs. You define an alias in the master catalog saying for data sets starting with a specific high level qualifier, use that user catalog.

When a userid was created, most system programmers would also create an alias pointing to a user catalog. They may define a user catalog for each user, or a user catalog could be shared by many aliases.

The catalogs are managed by the VSAM component of z/OS.

Entity naming

PDS and sequential files are referred to as datasets. VSAM provides simple database objects,

  • Relative Record ( where you say get me the n’th record)
  • Key sequence. You define a primary index, and you can an index on different columns using an ALTERNATIVE INDEX. 

VSAM uses the term cluster to what you use in you JCL or application. A cluster has a data component, and zero or more index components.

Moving systems.

I have been running on a self contained ADCD system at z/OS level 2.4. I have recently installed a self contained system at z/OS 2.5. How do I get my data sets into the new system?
You can import connect a user catalog into a new (master) catalog, and define an alias in the new master catalog pointing to the user catalog.

When I did this I could then see my COLIN.* data sets. To be able to use the data sets, I need the volumes to be attached to the z/OS system.

Useful IDCAMS commands

In batch you use the IDCAMS program (IDC = prefix for VSAM, AMS is for Access Management Services!)

If you do not specify a catalog, it defaults to the master catalog.

Create a user catalog

//IBMDF  JOB 1,MSGCLASS=H                                   
//S1  EXEC PGM=IDCAMS                                       
//SYSPRINT DD SYSOUT=*                                      
//SYSIN DD *                                                
 DEFINE USERCATALOG -                                       
      ( NAME('A4USR1.ICFCAT') -                             
        MEGABYTES(15 15) -                                  
        VOLUME(A4USR1) -                                    
        ICFCATALOG  -                                       
        FREESPACE(10 10) -                                  
        STRNO(3  ) ) -                                      
        DATA( CONTROLINTERVALSIZE(4096) -                   
              BUFND(4) ) -                                  
        INDEX(BUFNI(4) )                                    
/*

Creating an alias to use the catalog

The JCL below creates two aliases in the master catalog. They both point to a catalog called A4USR1.ICFCAT (which is in the master catalog)

//IBMUSERT JOB 1,MSGCLASS=H                                     
//S1  EXEC PGM=IDCAMS,REGION=0M                                 
//SYSPRINT DD SYSOUT=*                                          
//SYSIN DD *                                                    
   DEFINE ALIAS (NAME(BACKUP) RELATE('A4USR1.ICFCAT') )         
   DEFINE ALIAS (NAME(COLIN ) RELATE('A4USR1.ICFCAT') )         
/*

To import an existing user catalog into a master catalog

//IBMUSERT JOB 1,MSGCLASS=H                                   
//S1  EXEC PGM=IDCAMS,REGION=0M                               
//SYSPRINT DD SYSOUT=*                                        
//SYSIN DD *                                                  
   IMPORT CONNECT -                                           
      OBJECTS -                                               
        (('A4USR1.ICFCAT' VOLUME(A4USR1) DEVICETYPE(3390)  -  
        ))                                                    
/*

From the information provided, the master catalog knows the name, and location of the user catalog.

List an entry

You can list information about an entry, such as a data set, or a catalog using the LISTCAT command

LISTCAT ENT(COLIN.USERS) ALL

Listing aliases

You can use the IDCAMS command LISTCAT with alias

LISTCAT ALIAS

which gives a one line per entry list of all of the aliases

ALIAS --------- ADCDA       
ALIAS --------- ADCDB       
ALIAS --------- ADCDC       
ALIAS --------- ADCDD       
...

LISTCAT ALIAS ALL

gives 

ALIAS --------- ADCDA                                                       
     ...          
     ENCRYPTIONDATA                                                         
       DATA SET ENCRYPTION-----(NO)                                         
     ASSOCIATIONS                                                           
       USERCAT--USERCAT.Z24C.USER                                           
ALIAS --------- ADCDB                                                       
    ...      
     ENCRYPTIONDATA                                                         
       DATA SET ENCRYPTION-----(NO)                                         
     ASSOCIATIONS
       USERCAT--USERCAT.Z24C.USER

So we can see that the the alias ADCDA maps to user catalog USERCAT.Z24C.USER

Listing a catalog

The command

LISTCAT CATALOG(USERCAT.Z24C.USER)

gives

CLUSTER ------- 00000000000000000000000000000000000000000000       
   DATA ------- USERCAT.Z24C.USER                                  
   INDEX ------ USERCAT.Z24C.USER.CATINDEX                         
NONVSAM ------- ADCDA.S0W1.ISPF.ISPPROF                            
NONVSAM ------- ADCDA.S0W1.SPFLOG1.LIST                            
NONVSAM ------- ADCDB.S0W1.ISPF.ISPPROF                            
...                           
CLUSTER ------- SYS1.VVDS.VC4CFG1                                  
   DATA ------- SYS1.VVDS.VC4CFG1

Which shows there is a data component of the catalog called USERCAT.Z24C.USER, and there is index component called USERCAT.Z24C.USER.CATINDEX.

The catalog has a data component (USERCAT.Z24C.USER) and an index component USERCAT.Z24C.USER.CATINDEX.

Within the catalog are entries for data sets such as ADCDA.S0W1.ISPF.ISPPROF, and system (DFDSS) dataset SYS1.VVDS.VC4CFG1 - which contains information what is on the SMS DASD volume C4CFG1.

Where’s my packet gone? How can I see it being discarded.

I was testing out tracing TCP/IP on z/OS and wondered why I was not seeing packets with a bad destination address in the trace. I’ve now found out WHY I cannot see them, it’s just a little extra complexity of TCP/IP.

I had configured my z/OS to have an IP address of 7.1.168.74, and I could trace the packet. When I defined a route to z/OS for 7.168.1.>75< it did not appear in my trace even as an undeliverable packet.

My configuration was 

  INTERFACE TAP1 
     DEFINE IPAQENET 
     CHPIDTYPE OSD 
     IPADDR 7.168.1.74 
;     PRIROUTER 
     PORTNAME PORTB 
 START TAP1

If you add the PRIROUTER option, my packet appeared in the trace. The documentation says

The primary router stack is the only stack to which OSA forwards packets when the destination IP address has not been previously registered with OSA. If no active TCP/IP instance using this device is defined as the primary router (PRIROUTER) or secondary router (SECROUTER), the device discards the datagram.

I think of an OSA as a clever hardware socket where you plug your Ethernet cable into the side of the z/OS box. Amongst other things, it drops traffic not destined for the z/OS image(s).

The quoted text means the OSA is doing some of the network work, and dropping packets not destined for the z/OS image(s), and so less work for z/OS.

With PRIROUTER I had a trace record, and the drop reason code was 4167, IP_NO_FWD: the packet cannot be forwarded, as expected.

Can I see this in NETSTAT output?

When I use NETSTAT STATS, it now has

Received Address Errors = 5

When I use NETSTAT DEVLINKS, the interface now has

Inbound Packets In Error = 5

When PRIROUTE is not specified, these values are 0.

MFA messages

Other posts on MFA:

AZF2406E Error from R_factor (AZFTOTP1) (length=0)

The RACF definitions have been done, you need to the the AZFEXEC processing for the factor (AZFTOTP1)

From Curl on Linux

curl: (35) error:0A00010B:SSL routines::wrong version number

The policy agent was not started on z/OS

ANZ#IN01 : IO error while writing, errno=140 reason=76697242

The policy agent was not running.

Browser: Secure Connection Failed An error occurred during a connection to … SSL received a record that exceeded the maximum permissible length.

Error code: SSL_ERROR_RX_RECORD_TOO_LONG

The policy agent was not started on z/OS

AZF2606E Failed to listen on loopback address (port:6792. rc:1115, rsn:0x744c7247)

There were two instances of AZF#IN00 active at the time (I was shutting one down, and restarting it)

Action: Wait till the first instance has stopped and then restart it.