Dovetailed Technologies

Name

getpds — Copy PDS(E) member(s) to UNIX file(s)

Synopsis

getpds [OPTION...] //dataset.name dest_dir
getpds [OPTION...] //dataset.name(member-pattern) dest_dir
getpds [OPTION...] //dataset.name(member) dest_file
getpds -h
getpds -v
    

Description

The getpds command copies PDS(E) member(s) to UNIX file(s). The records for each member are converted to a stream of bytes in the UNIX file, depending on the options provided. By default, records are written as text with newline separators and trailing blanks trimmed from fixed length record formats.

dataset.name is either an MVS PDS or PDS/E dataset, preceded by '//'. The name is assumed to be a fully qualified DSN, unless the -r option is used. Supported record formats include: RECFM=F(B), V(B), and U. RECFM=VBS is not supported, and statistics processing is not available with RECFM=U. Load modules, program objects, aliases, or other members with user TTRNs will not be copied.

If (member-pattern) is given, it may be either a comma separated list of up to 9 member names or wild card patterns with '*' or '?'.

If (member) is a single member name and dest_file (not a directory) is given, then that file name will be used as given and may be "-" for printing to stdout.

Otherwise, selected members will be copied to filenames memname[.suffix] in the destination directory, depending on -M member processing options.

In a shell you will need to quote "//dataset.name(member)" since ( and ) are meta characters. member names or patterns with the '$' character will need to be either escaped or enclosed in single quotes, again to avoid processing by the shell.

Options

-b

Specifies that the data should be transfered in "binary", i.e translation is disabled. Setting this option implies: -k -l none -p 0x00.

-h

display help and exit.

-k

keep trailing spaces in record; default is to trim spaces for fixed records.

-K

always trim trailing spaces.

-l line-separator

nl | cr | lf | crlf | crnl

follow lines with a newline, carriage return, linefeed, or combination. The characters are taken from the target codepage. The default is nl.

rdw

preceed lines with a four byte IBM-style RDW, consisting of a two byte network order (big endian) length, followed by two bytes of zeros.

l4

preceed lines with a four byte network order (big endian) length of the record that follows. Note: Unlike the rdw option, this length value does not include the size of the length field.

mfrdw

Write a 128 byte MicroFocus standard header prior to output data. Preceed each line with a network order (big endian) length. If the maximum record length is < 4095 bytes, the length field is 2 bytes. If the maximum record length is >= 4095 bytes, the length field is 4 bytes. Each line is padded with zeros to the nearest 4 byte boundary.

0xbb[bb..]

follow lines with a hex character sequence. The sequence must be between 1 and 8 bytes long.

none

no line separator

-L logging-options

A comma-separated list of options to control logging and tracing.

M | A | C | E | W | N | I | D | T | F

Logging threshhold: eMergency, Alert, Critical, Error, Warning, Notice (default), Info, Debug, Trace, Fine.

t

Prefix log messages with a system timestamp

e

Include consumed cpu time in log messages

f=filename

Messages are logged to filename on the server instead of stderr. If not fully qualified, the file is written to the user's home directory on the server.

component=M|A|C|E|W|N|I|D|T|F

Set the logging threshold for a specific component. Specify only at the request of product support personnel.

-p 0xbb

pad character.

-q technique-str

Codepage conversion technique string. Used to override the default Unicode Services value of LMREC. For more information, see IBM's Unicode Services User's Guide and Reference (SA22-7649).

-r

dataset-name will be prefixed with the current z/OS userid.

-s source-codepage

The codepage name or numeric CCSID id of the input dataset. If not specified, then the default z/OS codepage for the current process is used.

-t target-codepage

The codepage name or numeric CCSID id of data written to stdout. If not specified and invoked from a remote client with a line- separater other than 'none', 'rdw' or 'mfrdw', then the default client codepage is used, otherwise the default z/OS code- page is used. Translation is disabled if source-codepage equals target-codepage.

-T STANDARD | translate_table_dsname

Specifies the translate table to use for text mode transfers. This option overrides the -s -t -q options if also given. If STANDARD, the translate table TCPIP.STANDARD.TCPXLBIN is used. If a dataset name is supplied, it is expected to be in the format produced by the TSO CONVXLAT command. Only single byte translations are supported. Specifically, the dataset DCB must be LRECL=256,RECFM=F and contain two translation table records. The first record is an ASCII-to-EBCDIC mapping; the second record is an EBCDIC-to-ASCII mapping. Additional comment records (starting with * in the first column) are allowed.

-M keyword=value[,keyword=value...] member processing options

A comma-separated list of keyword and value pairs for specifying member processing options.

mt[ime]=c[urrent]|m[ember]

file mtimes set to current(default) or member stats time (if present).

r[eplace]=y[es]|n[o]

if yes (default) then existing target files may be replaced.

su[ffix]=suffix

suffix added to member name to generate file names. This is ignored if a specific single member and target file (not a directory) are given on the command

st[atsfile]=filename

used with the zigi product to write/update statistics for members to a file. The filename may be specified as - to print member stats to stdout.

tag=y[es]|n[o]

if 'yes', copied files are tagged as text with the target -t codepage (or its default) or tagged as binary if the target files contain binary data (e.g. -b)). The default is no tagging.

upp[ercase]=y[es]|n[o]

file member names uppercased? (default=no: lower case)

up[date]=a[all]

copy all selected members (default)

up[date]=n[ewer]

only copy members with stats that are newer than target file mtime, or statsfile entry if specified. This also copies if members (or statsfile) stats are not present.

-v

display the current version and exit.

Examples

  1. This example copies all of the members of a PDS to the current directory (".")

    $ getpds //sys1.maclib . 
    getpds(SYS1.MACLIB)[N]: 2015 members/2435218 records/194817440 bytes read; 
                            194011101 bytes written in 1.791 seconds (103.307 MBytes/sec).
    
  2. This example is the same, but -LI(nfo) level logging is used and file names are created with a suffix.

    $ getpds -LI -M suffix=mac //sys1.maclib .
    getpds(SYS1.MACLIB)[I]: copied ABEND    -> ./abend.mac
    getpds(SYS1.MACLIB)[I]: copied ACB      -> ./acb.mac
    getpds(SYS1.MACLIB)[I]: copied ACBVS    -> ./acbvs.mac
    ...
    getpds(SYS1.MACLIB)[I]: copied XLATE    -> ./xlate.mac
    getpds(SYS1.MACLIB)[I]: copied YREGS    -> ./yregs.mac
    getpds(SYS1.MACLIB)[N]: 2015 members/2435218 records/194817440 bytes read; 
                            194011101 bytes written in 2.030 seconds (91.144 MBytes/sec).
    
  3. In this example, statistics are printed (-M st=-) for a PDS, but no files are copied since a target directory is not given as the last argument.

    $ getpds -M st=- //KIRK.ADMIN.JCL
    ACSSTORC 96/12/02 17/10/02  1  2 14:22:50   104    57     0 IBMUSER
    ACSSTORG 99/12/01 17/10/02  1  1 14:23:53    45    38     0 IBMUSER
    ADDVOL   20/08/31 20/08/31  1  1 09:21:12     7     7     0 IBMUSER
    ALTSC    17/08/18 17/08/18  1  0 14:20:53     5     5     0 KIRK
    AMATERSE 18/02/07 18/02/19  1  2 10:22:36     7     7     0 KIRK
    CATEXP   17/10/04 17/10/04  1  0 09:19:51    17    17     0 IBMUSER
    CATIMP   17/08/17 17/08/18  1  2 08:42:25    12     9     0 IBMUSER
    CONVERTV 17/10/02 17/10/04  1  6 09:27:16    23    21     0 IBMUSER
    DEFACDS  96/08/05 17/10/02  1  4 14:06:17    17    16     0 IBMUSER
    DEFALIAS 17/10/04 17/10/04  1  0 10:03:23    17    17     0 IBMUSER
    DEFSCDS  96/12/15 17/10/02  1  3 14:12:50    26    25     0 IBMUSER
    DELETE   17/08/18 17/10/03  1  4 12:52:05    39    33     0 IBMUSER
    DFDSSB   19/02/06 19/02/06  1  0 11:55:26    42    42     0 IBMUSER
    DFDSSR   20/03/24 20/03/24  1  0 15:06:29    12    12     0 IBMUSER
    IEHPROGM 17/10/02 17/10/02  1  5 18:20:21    75    15     0 IBMUSER
    INSTALL  13/03/25 18/05/11  1 55 14:43:02    24    28     0 IBMUSER
    INSTALL2 13/03/25 18/05/17  1 57 10:48:39    24    28     0 IBMUSER
    MOVE     17/09/29 17/09/29  1  0 15:50:28    13    13     0 KIRK
    PASSTICK 17/08/23 20/06/10  1  1 10:54:05    27    27     0 IBMUSER
    RACFCSR  18/02/20 18/02/20  1  1 16:21:05    76    75     0 IBMUSER
    RECAT    17/08/18 17/08/18  1  1 09:25:07   116    62     0 IBMUSER
    SCRATCH  17/10/02 17/10/02  1  1 17:04:12    20    14     0 IBMUSER
    SYSINFO 
    Z13REST  17/08/18 17/08/18  1  1 15:39:30    42    40     0 KIRK
    getpds(KIRK.ADMIN.JCL)[N]: 0 members/0 records/0 bytes read; 0 bytes written in 0 milliseconds.
    
  4. Here statistics are saved to a file and the members are copied. The -M mtime=member option is used so that files will get their mtimes from the member statistics.

    $ getpds -LI -M st=ispf-stats,mt=m //KIRK.ADMIN.JCL .
    getpds(KIRK.ADMIN.JCL)[I]: copied ACSSTORC -> ./acsstorc
    getpds(KIRK.ADMIN.JCL)[I]: copied ACSSTORG -> ./acsstorg
    ...
    getpds(KIRK.ADMIN.JCL)[I]: copied Z13REST  -> ./z13rest
    getpds(KIRK.ADMIN.JCL)[N]: 24 members/945 records/75600 bytes read; 
                                   38796 bytes written in 0.011 seconds (3444.247 KBytes/sec).
    
  5. In this example we do the same, but only copy members with newer statistics than those present in the statsfile (-M update=newer). As you can see, only the member with no statistics is copied.

    $ getpds -LI -M st=ispf-stats,mt=m,upd=n //KIRK.ADMIN.JCL .
    getpds(KIRK.ADMIN.JCL)[I]: copied SYSINFO  -> ./sysinfo
    getpds(KIRK.ADMIN.JCL)[N]: 1 members/155 records/12400 bytes read; 
                                   7967 bytes written in 0.001 seconds (7780.273 KBytes/sec).
    
  6. In this next example we do the same, but without a statistics file. The (-M update=newer) option will now use any existing file's mtime to determine if the member is newer. Since we have been using -M mtime=m, the files mtimes already match the member statistics. Again, only the member with no statistics (indeterminate age) will be copied.

    $ getpds -LI -M mt=m,upd=n //KIRK.ADMIN.JCL .
    getpds(KIRK.ADMIN.JCL)[I]: copied SYSINFO  -> ./sysinfo
    getpds(KIRK.ADMIN.JCL)[N]: 1 members/155 records/12400 bytes read; 
                                   7967 bytes written in 0.001 seconds (7780.273 KBytes/sec).
    
  7. Here we use a list of member patterns and names to select a subset of members to copy. Quotes are used to prevent the shell from interpreting parentheses as shell meta characters, although these quotes are removed by the shell before invoking the command.

    $ getpds -LI //KIRK.ADMIN.JCL'(ACS*,INS*,SYSINFO)' . 
    getpds(KIRK.ADMIN.JCL)[I]: copied ACSSTORC -> ./acsstorc
    getpds(KIRK.ADMIN.JCL)[I]: copied ACSSTORG -> ./acsstorg
    getpds(KIRK.ADMIN.JCL)[I]: copied INSTALL  -> ./install
    getpds(KIRK.ADMIN.JCL)[I]: copied INSTALL2 -> ./install2
    getpds(KIRK.ADMIN.JCL)[I]: copied SYSINFO  -> ./sysinfo
    getpds(KIRK.ADMIN.JCL)[N]: 5 members/352 records/28160 bytes read; 
                               14841 bytes written in 0.003 seconds (4831.055 KBytes/sec).
    

See Also

putpds(1)

copypds(1)

fromdsn(1)

todsn(1)

Copyright© 2009-2020 Dovetailed Technologies, LLC. All rights reserved.
Co:Z® is a registered trademark of Dovetailed Technologies, LLC.