MVSCMDAUTH(1)
NAME
mvscmdauth - Run an authorized MVS command (program) that resides in a PDS or PDSE from the UNIX System Services command line. To run an unauthorized MVS command (program), use mvscmd.
SYNOPSIS
mvscmdauth [opt]*
Where opt is one or more of:
--buildinfo | -b
Display build information of this program.
--help | --info | -h
Display this help message.
--pgm=<name> | -p=<name>
Specify the program to run, e.g. -p=iebcopy
--steplib=<dataset>
Specify dataset to search for program. For example: --steplib=MY.DATASET.
By default, mvscmdauth searches the STEPLIB linklist for the specified
program.
--args=<args> | -a=<args>
The program arguments, such as -a='MARGINS(1,72)'. Default is ''.
--verbose | -v
Display verbose messages.
--debug | -d
Display even more verbose messages and retain temporary datasets.
--json | -j
Print output in JSON format. The output has the following structure:
{
"data": {
"STEPLIB": "none",
"program": "IEBCOPY",
"DDs": [
{
"ddname": "SYSOUT",
"type": "console",
"name": "IBMUSER.P0000001.T0000001",
"retained": false,
"content": "sample text\n",
"content_length": 12
}
]
},
"program": "mvscmdauth",
"rc": "0",
"options": "-j --pgm=iefbr14 --sysout=*"
}
--prettyjson | -J
Print JSON output in a readable format, with line breaks and indentation.
--tmphlq=<tmphlq> | -Q=<tmphlq>
Override the default high-level qualifier (HLQ) used for temporary dataset
names, which also overrides the TMPHLQ environment variable if set.
The default HLQ is based on the login name of the current user.
--<ddname>=<value>,[<options>]*
Specify a DDName to associate with a dataset, UNIX file, or volume.
Typically, no options are required. Options are ignored for STEPLIB
DDNames.
Valid options are:
excl
Allocate this dataset exclusively. If other jobs have
allocated this dataset already then the allocation will
fail. If the allocation succeeds, no other job can
allocate this dataset until this program completes.
old
Synonym for 'excl'
mod
Allocate dataset or file for update (modification).
vol
Allocate the DD name to a volume. Unlike dataset allocation,
the value specified is the volume name.
volume
Synonym for 'vol'
vio
Allocate the dataset as a virtual I/O DD name, if possible.
new
Create dataset. Dataset creation default values are the same
for mvscmd, mvscmdauth, and dtouch.
Suboptions for the 'new' operator are as follows:
type
May be one of: KSDS, ESDS, RRDS, LDS, SEQ/BASIC, LARGE,
PDS, PDSE/LIBRARY, HFS.
Default is 'PDSE'.
For types with multiple names (SEQ/BASIC, PDSE/LIBRARY),
either name may be used.
primary
Is the amount of primary space to allocate for the dataset.
Default is 5M.
Size may include a suffix of K or KB (kilobytes),
M or MB (megabytes), G or GB (gigabytes),
C or CYL (cylinders), T or TRK (tracks).
secondary
The amount of secondary space to allocate for the dataset.
Size of extents. Defaults to 1/10 of primary space amount.
Size may include a suffix of K or KB (kilobytes),
M or MB (megabytes), G or GB (gigabytes),
C or CYL (cylinders), T or TRK (tracks).
spfrm
The format of allocated space to use when allocating the
dataset. May be one of:
ALX
Different areas of contiguous space are to be
allocated.
MXIG
Maximum contiguous space is required.
CONTIG
Space must be contiguous.
normdisp
Tells the system what to do with the dataset after normal
termination of the program.
May be one of delete, keep, catalog, uncatalog.
Defaults to 'catalog'.
conddisp
Tells the system what to do with the dataset after
abnormal termination of the program.
May be one of delete, keep, catalog, uncatalog.
Defaults to 'catalog'.
dirblks
The number of directory blocks for a PDS. Optional
parameter for PDS datasets. Default is 5.
blksize
The block size of the dataset. Defaults are as follows:
32718 for record format FBA,
32720 for FB,
32743 for VBA,
32760 for VB and U.
recfm
The record format for the dataset.
One of FB, VB, FBA, VBA, U. Default is 'FB'.
lrecl
Logical record length, in bytes, of each record in the dataset.
Expressed in bytes. Defaults are as follows:
80 for fixed datasets (FB, FBA),
137 for variable datasets (VB, VBA)
0 for unformatted datasets (U)
For variable datasets, the length must include the
4-byte prefix area.
dsorg
The dataset organization of the dataset. May be one
of GS, PS, PSU, PO, POU, DA, DAU, IS, ISU.
Defaults are as follows:
PS for sequential datasets (SEQ/BASIC/LARGE),
PS for zFS datasets,
PO for partitioned datasets (PDS/PDSE/LIBRARY).
storclas
The storage class for an SMS-managed dataset.
Required for SMS-managed datasets that do not match an
SMS-rule. Not valid for datasets that are not
SMS-managed. Note that all non-linear VSAM datasets are
SMS-managed.
dataclas
The data class for an SMS-managed dataset. Optional for
SMS-managed datasets that do not match an SMS-rule.
Not valid for datasets that are not SMS-managed.
Note that all non-linear VSAM datasets are SMS-managed.
mgmtclas
The management class for an SMS-managed dataset.
Optional for SMS-managed datasets that do not match an
SMS-rule. Not valid for datasets that are not
SMS-managed. Note that all non-linear VSAM datasets are
SMS-managed.
keylen
Length, in bytes, for each record's key in
Key Sequenced Datasets (KSDS).
keyoffset
Bytes from the beginning of each record where the key is located.
Required for Key Sequenced Datasets (KSDS).
volumes
A list of comma separated volume serials. When
providing multiple volumes, processing will begin with
the first volume in the provided list. Offline volumes
are not considered. Volumes can always be provided when
not using SMS. When using SMS, volumes can be provided
when the storage class being used has
GUARANTEED_SPACE=YES specified. Otherwise, the
allocation will fail.
dskeylbl
The label for the encryption key used by the system to
encrypt the dataset. Only applicable when using
encrypted datasets.
keylab1
The label for the key encrypting key used by the
Encryption Key Manager. Only applicable when using
encrypted datasets.
keycd1
How the label for the key encrypting key specified by
keylab1 is encoded by the Encryption Key Manager.
May be one of: L, H
Only applicable when using encrypted datasets.
keylab2
The label for the key encrypting key used by the
Encryption Key Manager. Only applicable when using
encrypted datasets.
keycd2
How the label for the key encrypting key specified by
keylab2 is encoded by the Encryption Key Manager.
May be one of: L, H
Only applicable when using encrypted datasets.
For UNIX files:
normdisp
Tells the system what to do with the UNIX file after normal
termination of the program.
May be 'keep' or 'delete'. Defaults to 'keep'.
conddisp
Tells the system what to do with the UNIX file after abnormal
termination of the program.
May be 'keep' or 'delete'. Defaults to 'keep'.
pathmode
The file access attributes for the UNIX file being allocated.
Provide in chmod-like number format. (e.g. 0644, 1777)
If missing leading number assumes 0 (e.g. 644 == 0644)
statusgroup
The status for UNIX file being allocated.
Specify up to 6 of: OCREAT, OEXCL, OAPPEND, ORDWR, ORDONLY,
OWRONLY, ONOCTTY, ONONBLOCK, OSYNC, OTRUNC.
Provide multiple attributes as comma separated list.
filedata
The type of data that is (or will be) stored in the UNIX file.
May be 'binary', 'record', or 'text'.
lrecl
Use the specified logical record length for the UNIX file being
allocated. This is required in situations where the data is
processed as records.
The record length, block size and record format need to be supplied
because UNIX files are normally treated as a stream of bytes.
blksize
Use the specified block size for the UNIX file being allocated.
This is necessary because UNIX files are normally treated as a
stream of bytes.
recfm
Use the specified record format for the UNIX file being allocated.
This is necessary because a UNIX file is normally be treated as a
stream of bytes.
ENVIRONMENT VARIABLES
TMPHLQ
Overrides the current high-level qualifier used for temporary dataset names.
DESCRIPTION
Run an authorized MVS program in the current shell. This is analogous to a job step in JCL. In addition, mvscmdauth lets you read input from stdin and write output to stdout, which is very convenient for running mvscmdauth as part of a series of steps.
By default, mvscmdauth searches for the program (--pgm=<name>) in the linklist defined by the STEPLIB environmental variable. However, if you want to add a specific dataset to search for the program, you can use
--steplib=MY.DATASET to append this dataset to STEPLIB for this command. Users can display the list of datasets currently contained in STEPLIB by running the pll utility,
mvscmdauth is identical to mvscmd except for the name and that it runs authorized MVS programs instead of unauthorized MVS programs. For more details, see mvscmd.
EXAMPLES
Dataset example: allocate the DDName SYSIN to the dataset IBMUSER.TEST.OBJ:
--sysin=IBMUSER.TEST.OBJ
Concatenated dataset example: allocate the ddname SYSLIB to the dataset concatenation CEE.SCEELKED:CEE.SCEELKEX:
--syslib=CEE.SCEELKED:CEE.SCEELKEX
Concatenated dataset and path example: allocate the ddname SYSLIB to the dataset and UNIX path concatenation CEE.SCEELKED:/u/sysadm/sysfile:
--syslib=CEE.SCEELKED:/u/sysadm/sysfile
Concatenated dataset example allocating second dataset: allocate the ddname SYSLIB to the dataset concatenation MVSCMD.DSN1:MVSCMD.DS2 where MVSCMD.DS2 is created.
--syslib=MVSCMD.DSN1:MVSCMD.DS2,NEW,TYPE=SEQ,LRECL=80
Console example: allocate the DDName SYSPRINT to stdout (which can then be piped to other processes):
--sysprint=*
Console example (alternate):
--sysprint=stdout
stdin example: allocate the DDName SYSIN to an FB 80 temporary sequential dataset that has stdin written to it (stdin can be piped in from other processes):
--sysin=stdin
Dummy Dataset example: allocate the DDName SYSIN to DUMMY:
--sysin=dummy:
Dataset allocated as 'exclusive' (i.e. DISP=OLD) example:
--archive=IBMUSER.MVSCMD.DAR,EXCL
Dataset allocated as 'mod' (i.e. DISP=MOD) example:
--archive=IBMUSER.MVSCMD.DAR,MOD
Dataset allocated as 'new' (i.e. DISP=NEW) example:
--archive=IBMUSER.MVSCMD.DAR,NEW,TYPE=pdse,LRECL=80,BLKSIZE=32720,VOLUMES=SCR03,MYVOL1
UNIX file allocated as 'mod' (i.e. DISP=MOD or 'append') example:
--archive=/tmp/mylog,mod
Volume example: allocate the DDname DD2 to the VOLUME USER01 (as opposed to a particular dataset):
--dd2=user01,vol:
mvscmd invocation example: Compare 2 PDS members 'old' and 'new' and write the output to stdout:
echo " CMPCOLM 1:72" | mvscmd --pgm=isrsupc --args="DELTAL,LINECMP" --newdd='ibmuser.in(new)' --olddd='ibmuser.in(old)' --sysin=stdin --outdd=stdout
Specify program location: Specify a certain dataset to search for a particular program example:
mvscmd --pgm=<name> --steplib=MY.DATASET
EXIT VALUES
0
mvscmdauth completed without error.
non-zero
mvscmdauth failed or the MVS command (program) returned a non-zero value. See error messages for details.