The MASCMD utility is provided to allow the user to execute MAS console commands from the mainframe.
The MASCMD utility program can be found in the UIMFTP package distributed on the MAS Utilities CD. Install the UIMFTP modules as instructed in the MAS Installation and User’s Guide.
The MASCMD utility must be linked as an authorized program into an authorized library under the name MASCMD. It is highly recommended that RACF be used to restrict the use of MASCMD to authorized users only.
An example of the JCL to link MASCMD follows:
//L EXEC
PGM=HEWL,PARM='MAP,LET,LIST,NCAL,AC=1'
//SYSLMOD DD DSN=USER.LIBRARY,DISP=SHR
//SYSUT1 DD
DSN=&&SYSUT1,SPACE=(1024,(120,120),,,ROUND),
// UNIT=SYSALLDA,DCB=BUFNO=1
//SYSPRINT DD SYSOUT=*
//DDIN DD DSN=BTI.MODULE,DISP=SHR
//SYSLIN DD *
INCLUDE DDIN(MASCMD)
NAME MASCMD(R )
/*
The JCL to run MASCMD is as follows:
//LOG EXEC PGM=MASCMD
//MASCTRL DD DSN=MAS.CTRL,UNIT=V3480,VOL=SER=BT9999,DISP=(,KEEP)
//MASLOG DD DSN=MAS.LOGFILE,DISP=OLD
//MASCMD DD DSN=COMMANDS,DISP=OLD
This program will read one or more MAS commands from the MASCMD file, and send each command to the MAS. The MASCMD DD statement should point to a list of MAS commands to be sent. The LRECL of MASCMD cannot exceed 256. When possible, it should be created using the NONUM ISPF edit option to avoid sequence numbers at the end of the command line, which in many cases would cause a syntax error in the MAS command. MASCMD can optionally be an in-stream input file (MASCMD DD *) of commands, for example:
//LOG EXEC PGM=MASCMD
//MASCTRL DD
DSN=MAS.CTRL,UNIT=V3480,VOL=SER=BT9999,DISP=(,KEEP)
//MASLOG DD DSN=MAS.LOGFILE,DISP=OLD
//MASCMD DD *
SET SIZE=2G DEV=EA80
/*
The MASCTRL file is used to allocate a MAS virtual tape device for use as a control path to pass the MAS command(s). The designated volume will be mounted on the MAS for the duration of the program, but nothing will be written to the volume. It can be a specific volser or a scratch volume, unlabeled or IBM or ANSI labeled. If there are multiple MAS systems in use, the user must select a tape device address that is associated with the proper MAS to process the console commands.
The MASLOG DD card points to a sequential file for logging the results of the MASCMD program. This file should have a logical record length (LRECL) of 133.
If an error occurs during command processing, the failure will be recorded in the MASLOG file, and a non-zero return code from MASCMD execution will result. Note that the textual output that displays on the MAS console is not returned to the host. Only a success or failure indication will be returned to the MASCMD program. The possible error codes are as follows:
· 0x01 Invalid data length (must be between 1 and 256 bytes)
· 0x02 The MAS is configured to not accept host-initiated console commands
·
0xFF (-1) A general syntax error occurred.
(The MAS console error message “MAS891E: Invalid command syntax” was
displayed.)
·
0xFC (-4) An “E” level error other than general
syntax error occurred.
(A MAS console error message other than MAS891E was displayed.)
A sample MASLOG output might look as follows:
MASCMD
VER 1.0 MASCTRL = EA82
2004/09/10 12:47:49 CMD ERR=FF: this is
an invalid command
2004/09/10 12:47:49 CMD ISSUED: q all
2004/09/10 12:47:49 CMD ERR=FC: q
xxx (an invalid devicename)
2004/09/10 12:47:49 CMD ISSUED: set
size=2g dev=EA80
Any MAS console command except EXIT and RESTART can be sent to the MAS for execution. EXIT and RESTART can never be executed from the host.
Commands sent to the MAS via MASCMD can contain special variable values which will be substituted into the command line before the command is executed. These variables are:
$NAME Substitutes the Device Name of the device over which the MAS command was received (the MASCTRL device).
$VOLSER Substitutes the volume serial number of the tape currently mounted on the device over which the MAS command was received.
$PATH Substitutes the current tape library path of the device over which the MAS command was received.
For example, if the following command is sent to the MAS with device E980 assigned as MASCTRL:
SET SIZE=200M DEV=$NAME
the command that will be executed on the MAS console will be:
SET SIZE=200M DEV=E980
By default, the MAS will not accept any commands to be executed from the host. To enable this feature, the following new configuration parameter must be added to the MAS configuration file:
HOSTCOMMAND YES
This parameter is not currently recognized by the MAS GUI configuration program. You must use an editor such as vi or kwrite to add this line to the MAS configuration file. It can be added anywhere within the file, but it is recommended that it be added near the top of the file along with the other general purpose (non-device specific) parameters such as TRACELEVEL, etc. Once the new statement has been added to the configuration file, even though it can't be changed in the GUI configuration program, the configuration program will show it and leave it in the configuration file as-is during future configuration changes.
Example of a modified MAS configuration file:
#
/etc/bti/btixmap0
#
USERNAME btixmap0
DESCRIPTION MAS configuration 0
TRACELEVEL 1
HOSTCOMMAND YES
#
[DEVICE] ACTIVE=1 INDEX=00 NAME=10B0 TYPE=3490 UNIT=B0 CU=08 PATH=CENTERA1
IDRC=YES SIZE=10G
...