VMLINK

Authorization

General User

Purpose

Operands

Disk Operands

nickname

is a nickname defined in a CMS NAMES file by a :NICK tag. For more information on the tags used for VMLINK, see NAMES.

category

is a category name defined in a CMS NAMES file by a :CATEGORY tag. When a category name is specified, the VMLINK panel displays all nicknames in that category. When a disk operand is determined to be a category, any linking details entered are ignored.

.DIR dirname

identifies an SFS directory. When an SFS directory is specified this way, use the NONAMES option so VMLINK does not search any NAMES files.

user_ID owner_vdev

identifies the user ID of the owner of a minidisk and the 1-4 character hexadecimal virtual device number as defined in the owner’s user directory entry. When a minidisk is specified this way, use the NONAMES option so VMLINK does not search any NAMES files. Otherwise, VMLINK might match the user ID with a nickname. If an asterisk is used for user_ID, your user ID is used as the owner.

Linking Details

vdev

is the 1-4 character hexadecimal virtual device number at which a minidisk is to be linked. To select the next free virtual address in a range, specify the start of a range as +vdev or -vdev (ascending or descending order). If the disk is already linked and falls in the correct range, the existing virtual device is maintained. For example, if a disk is linked at 200 and +120 is specified as the vdev, the 200 link is kept. A vdev of 0 is not allowed because one cannot access a minidisk with an address of 0.

An asterisk selects the next free virtual address, as specified in the *VDEV record in the VMLINK CONTROL file, unless the disk is already linked in which case the virtual device the disk is linked at is maintained.

An equal sign tells VMLINK to use the vdev range specified on the :PRODUCT tag in the NAMES file if one is found; otherwise, it behaves as an asterisk.

For SFS directories, vdev is a place holder.

filemode

is the file mode letter at which the minidisk or SFS directory is to be accessed. You cannot use the file mode S. The file mode letter can be followed by a file mode number. The allowable file mode numbers are 0 to 6. Using a file mode number defines a subset of the files on the specified minidisk or SFS directory. Only the files with the file mode number specified are included in the user file directory and only those files can be read. When a file mode number is used, the minidisk or SFS directory is accessed as an extension of itself and therefore is accessed as R/O. If a file mode number of 0 is used, nothing is accessed unless the MODE0 option is used and the ACCESSM0 command is available and set to ON. To have the first free file mode letter in a range assigned, specify the range as filemode1-filemode2. In a range, only a file mode letter is valid for filemode1, but filemode2 can be a file mode letter or a file mode letter and a file mode number. If the disk is already accessed and falls in the correct range, the existing file mode is kept. For example, if a disk is accessed at G and F-K is specified as the file mode range, the G file mode is kept.

An asterisk selects the default range, as specified in the *MODES record in the VMLINK CONTROL file, unless the disk is already accessed, in which case the file mode at which the disk is accessed is kept. The product default in the VMLINK CONTROL file is Z-A, which means the search starts at Z and progresses toward A.

An equals sign tells VMLINK to use the file mode range specified on the :PRODUCT tag in the NAMES file, if one is found; otherwise, it behaves as an asterisk.

If no file mode is available in the range specified, a DMS1281E error results. VMLINK does not access over an already-accessed file mode unless a single file mode is specified, such as P or P/S. If the file mode is specified as P-P or P,P and P is already in use, a DMS1281E error occurs.

/ext

is the file mode of the parent minidisk or SFS directory. Files on the minidisk (vdev) or directory (dirname) being accessed are logically associated with files on the parent minidisk or directory. The minidisk or directory is considered a read-only extension. A parent minidisk or directory must be accessed in the search order before the extension. An equal sign tells VMLINK to access the minidisk or SFS directory as an extension of itself.

link_mode

specifies whether you get read/only or read/write access to the minidisk or SFS directory. For a minidisk, all modes defined for the CP LINK command are valid. The default is RR.

An asterisk specified for a minidisk link_mode means:

• If no link exists, RR will be used
• If a link already exists, the existing link will be used

For SFS, you can specify FORCERO or FORCERW. The default is:

• FORCERO if you do not own the SFS directory
• FORCERW if you own a file control SFS directory

Note: If you own a directory control SFS directory, FORCERW is the default unless someone else has the SFS directory accessed R/W, in which case FORCERO is the default.

An asterisk specified for an SFS directory link mode follows the default behavior as described above.

If it is unknown what the nickname represents, minidisk or SFS directory, use the READ and WRITE options, instead of link_mode, to ensure VMLINK uses the appropriate link modes.

An equal sign tells VMLINK to use the link mode specified on the :PRODUCT tag in the NAMES file if one is found; otherwise, it behaves as an asterisk.

DETach

detaches and releases a minidisk, if linked, or releases an SFS directory, if accessed.

When you detach a minidisk with the READ or WRITE option, VMLINK issues a warning message if you do not have the minidisk linked in the matching mode or if the minidisk remains linked in the other mode. The READ option is the default. When you detach an SFS directory, the SFS directory is released regardless of the mode it is accessed in.

RELease

releases a minidisk or SFS directory if already accessed.

Options

ADDfile(fileids)

lists additional NAMES files to be searched before the files in the *FILES control record and overrides the files listed in the *ADDFILE control record in VMLINK CONTROL. More than one file ID can be specified. The file name and file type can be .NO and will resolve to the user's node ID. The file type and mode of the last file name in the list can default to NAMES *.

ONLy(fileids)

specifies which NAMES files should be searched. The ONLY option overrides the *FILES and *ADDFILE control records. More than one file ID can be specified. The file name and file type can be .NO and will resolve to the user's node ID. The file type and mode of the last file name in the list can default to NAMES *.

APpend

appends the list of nicknames to the list displayed on the VMLINK menu. This option can be used only within the menu.

Autolink

Autolink SET

puts the disk operand in a list of minidisks and/or SFS directories to be accessed when you log on or IPL CMS. The minidisks and/or SFS directories are also linked and accessed when this is issued. If the minidisks and/or SFS directories cannot be linked/accessed, no AUTOLINKs are set. The list is kept in the LASTING GLOBALV file. Options are not saved in the list, so if nicknames are used, they must be in one of the default NAMES files. If this option is entered with no disk operands, it is ignored.

The autolinks are not made when you:

• IPL with the NOSPROF parameter: ipl cms parm nosprof
• Enter access (nodisk at the VM READ after the IPL is complete

When setting an autolink, you may get the message DMS2064E [RC=1], identifying the GLOBALV line was truncated. If you set many autolinks, you may get this message because the GLOBALV line is too long. See GLOBALV for information on this size restriction. Each category has its own line, so this problem should only occur when setting many autolinks for nicknames in a given category.

Autolink RUN

links and accesses the minidisks or accesses the SFS directories specified by Autolink SET. If both Autolink RUN and Autolink LIST are specified, only the first one specified is used. Any operands or other options are not used when this option is entered, with the exception of the TYPE and NOTYPE options.

Autolink DELete

deletes a minidisk or SFS directory from the list of things to be accessed when you log on or IPL CMS. Autolink DELETE does not detach or release any minidisk or SFS directories. If this option is entered with no disk operands, it is ignored.

Autolink LISt

displays the autolinks currently set. Here is an example of what is displayed if there is an autolink set for MYNICK:

Number Autolink  Setting
1      - MYNICK <= = =>

If no autolinks are set, message DMS739W No autolinks are set is issued. Any operands or other options are not used when this option is entered.

DEBUG

is provided to help aid in debugging problems. It will help identify from which NAMES file the nickname entry, if any, was obtained. Also, some messages from CP or CMS are displayed. The messages produced for the DEBUG option are for diagnostic purposes only and are not translated.

EXIT(execname parmlist)

names an exit exec to be called after each minidisk or SFS directory has been accessed.

Note: For more information, see the PREEXIT option.

FIlelist fn ft

causes VMLINK to issue a FILELIST command for files on the first minidisk or SFS directory accessed. If linking or accessing the minidisk or SFS directory fails, FILELIST is not issued. VMLINK returns the accessed minidisks and/or SFS directories to their prior status before it exits; to keep the minidisks and/or SFS directories accessed, use the KEEP option. FILELIST overrides any commands on the :INVOKE tag in the NAMES file. The default is FILELIST * *.

When options follow FILELIST, the fn and ft parameters are required.

Using this option is a shortcut way of saying INVOKE EXEC FILELIST fn ft .fm1.

When the POP option is used, VMLINK does not process the FILELIST option.

Force

forces a link at vdev. If some other device is attached at vdev, it is detached.

NOExit

specifies the :PREEXIT and :EXIT tags in the NAMES file are not used.

NOInvoke

specifies the :INVOKE tags in the NAMES file are not used.

NOKeep

is used with FILELIST or INVOKE to restore minidisks and/or SFS directories to their prior status after VMLINK has finished. This is the default.

NOKEEP has no effect when neither FILELIST nor INVOKE is specified.

If the FORCE option or linking details of either RELEASE or DETACH are specified on the command, it may not be possible to restore the minidisks or directories that have been detached or released by the command.

Keep

is used with FILELIST or INVOKE to keep minidisks and/or SFS directories accessed after VMLINK has finished. It has no effect when FILELIST or INVOKE is not used.

NOList

specifies the :LIST tags in the NAMES file are not used.

NOMODE0

specifies mode 0 links will not be done. This is the default.

MODE0

specifies mode 0 links will be done provided the ACCESSM0 command is available and on. If ACCESSM0 is not available, an error message is displayed.

NONames

suppresses the search of NAMES files. Use NONAMES when the minidisk is identified by user_ID owner_vdev, or the SFS directory is identified by .DIR dirname.

QUEry

displays all NAMES file entries for each specified nickname regardless of the nodes specified on any :NODE tag. When this option is used the nickname is not processed, therefore no actions are taken on the nickname. All disk operands passed in are considered nicknames when this option is specified.

NONICKtrans

tells VMLINK not to call the VMLNICXT EXEC, which is an exit exec that can be locally customized. The function of this exit exec is to replace a specified nickname with another before the NAMES files are searched. For more information, see Testing with the VMLNICXT EXEC in z/VM: CMS User's Guide.

If VMLNICXT EXEC exists, it is called unless this option is specified.

PREExit(execname parmlist)

names an exit exec to be called after VMLINK has located a free virtual device number and file mode letter and before the minidisk or SFS directory is accessed. The parameter list can include all the VMLINK variables except .AS, .LA, and .LS.

Usage Notes for PREExit:

• The exit exec is called separately for each minidisk or SFS directory accessed by the VMLINK command and has access to variable and tag data for the minidisk or SFS directory only.
• A disk identifier is always passed to the exit as the first argument.
• A parameter list passed to an exit cannot include a right parenthesis. The first right parenthesis encountered indicates the end of the exit’s parameter list. If a right parenthesis is needed, use the :EXIT or :PREEXIT tags in the NAMES file, rather than the option.
• If a non-zero return code is returned from the exit exec, VMLINK ends. A return code of 12 terminates VMLINK with a return code 0. Otherwise VMLINK terminates with a return code in the form 3xxx, where xxx is the return code from the exit.
• This option overrides the equivalent tag in the NAMES file.
• It is used in addition to any exit specified in the VMLINK CONTROL file.
• When the POP option, the DETACH operand, or the RELEASE operand is used, VMLINK does not call exit execs.

PROFile fn

names the XEDIT profile for the VMLINK panel. The default is PROFVMLK. For more information on the PROFVMLK macro, see Default Key Settings.

PUsh

causes VMLINK to keep a record of its actions when it links and accesses minidisks and SFS directories in read/only mode. This record is kept by stacking the information in LIFO order. A later call to VMLINK for a minidisk or SFS directory with the POP option restores it to its former state.

Note: WRITE disk status is not saved or restored using this option.

POP

POP DETach

causes VMLINK to restore specified minidisks and/or SFS directories to their previous states, based on information saved by linking with the PUSH option. This is done by taking items off the stack in the reverse order of how they were stacked by PUSH; therefore, if an item in the middle of the stack is requested with the POP option, all subsequent items stacked by using the PUSH option will be restored with this POP. If a disk has been detached since the PUSH was done, the disk cannot be restored. If no disk operand is specified with this option, all minidisks and/or SFS directories for which information has been saved are restored.

WRITE disk status is not saved or restored using this option.

When POP is specified, VMLINK ignores linking details and does not call exit execs, run invoke routines, or process the FILELIST option.

POP RELease

causes VMLINK to restore specified minidisks and/or SFS directories to their previous states, based on information saved by linking with the PUSH option, except the minidisks are not detached. This is done by taking items off the stack in the reverse order of how they were stacked by PUSH; therefore, if an item in the middle of the stack is requested with the POP option, all subsequent items stacked by using the PUSH option will be restored with this POP. If a disk has been detached since the PUSH was done, the disk cannot be restored. If no disk operand is specified with this option, all minidisks and/or SFS directories for which information has been saved are restored.

WRITE disk status is not saved or restored using this option.

When POP is specified, VMLINK ignores linking details and does not call exit execs, run invoke routines, or process the FILELIST option.

PW password

specifies a password to be used for the CP link command. The password applies to all minidisks linked. For SFS directories, this option is not used.

READ

accesses the minidisk or SFS directory in read/only mode regardless of the NAMES file default. Minidisks are linked with a link mode of RR. SFS directories are accessed with FORCERO. For minidisks, an existing write link to the same minidisk is not disturbed, unless the same virtual device number is provided.

READ overrides any link_mode specified in the linking details and limits the effect of DETACH on minidisks to those linked in read mode. If it is unknown what the nickname represents, minidisk or SFS directory, use the READ option, instead of link_mode, to ensure VMLINK gets the minidisk or SFS directory in read/only mode.

Write

accesses the minidisk or SFS directory in write mode regardless of the NAMES file default. Minidisks are linked with a link mode of M. SFS directories are accessed with FORCERW. For minidisks, an existing read/only link to the same minidisk is not disturbed, unless the same virtual device number is provided.

WRITE overrides any link_mode specified in the linking details and limits the effect of DETACH on minidisks to those linked in write mode. If it is unknown what the nickname represents, minidisk or SFS directory, use the WRITE option, instead of link_mode, to ensure VMLINK gets the minidisk or SFS directory in write mode.

Save

causes VMLINK to save the program stack and restore it after VMLINK is done. Any stacked data is not available to the INVOKE routine. This is the default.

NOSave

prevents VMLINK from saving and clearing the program stack, so routines called with the INVOKE option or :INVOKE tag can use the data on the stack.

STACK FIFO

STACK

FIFO

specifies the returned data should be stacked FIFO. This is the default if return data is requested.

STACK LIFO

LIFO

specifies the returned data should be stacked LIFO.

STEM stem.

specifies the returned data should be returned to the calling program by setting a stem variable. If a stem name is not provided, VMLINK. is used as the default.

Type

displays warning and informational messages on the terminal. This is the default.

NOType

prevents warning and informational messages from being displayed on the terminal.

Invoke environment cmd_name parmlist

names routines to be executed after all the minidisks and/or SFS directories have been accessed. If linking or accessing the minidisk or SFS directory fails, the invoke routines are not executed. VMLINK returns the accessed minidisks and/or SFS directories to their prior status before it exits; to keep the minidisks and/or SFS directories accessed, use the KEEP option.

The INVOKE option overrides the :INVOKE tag in the NAMES files.

If used, the INVOKE option must be the last option specified and cannot be used with PARMS.

When the POP option is used, VMLINK does not run invoke routines.

About the parameter list:

• All text following INVOKE is considered part of its parameter list.
• More than one set of environment cmd_name parmlist can be used, delimited by semicolons. To pass a literal semicolon as a parameter, specify two adjacent semicolons.
• The environment is optional; the default is to invoke cmd_name as though from the CMS command line. Environments that can be specified are:

  MACRO

  to invoke cmd_name as an XEDIT macro.

  EXEC

  to invoke cmd_name as an exec.

  MODULE

  to invoke cmd_name in the command environment (like REXX/VM address COMMAND). CP commands must be preceded by CP, and execs by EXEC.

If VMLINK receives a non-zero return code from a routine, VMLINK issues message number 2884E with the routine name and a non-zero return code. If multiple routines are invoked, this message is issued for each routine that passes back a non-zero return code to VMLINK. VMLINK terminates with a return code in the form 3xxx, where xxx is the sum of the non-zero return codes from the invoked routines.

Parms parms

specifies parameters on the command invocation to be passed to routines called with the EXIT, PREEXIT, or INVOKE options or the :EXIT, :PREEXIT, or :INVOKE tags. You may use the .PA variable in a routine’s parameter list; the VMLINK command replaces .PA with parms. The list of parameters specified with PARMS can include any of the VMLINK variables.

All text following the PARMS option is considered part of the parameter list, so PARMS must be the last option specified.

Returned Data

.MSG

puts VMLINK messages prefixed with *.MSG on the stack if the STACK option was specified or prefixed with .MSG in REXX stem variables if the STEM option was specified. The default is to display messages at the terminal. When messages are stacked or placed in REXX stem variables, the entire message is always provided regardless of the CP EMSG setting. Messages are returned before any other returned data.

:tagname

returns the value assigned to the tag in the names file.

VMLINK Variables

VMLINK Variables can be used as part of the parameter lists for PARMS, invoke routines, pre exits and exits.

.ARn

returns the operands specified on the VMLINK command. The arguments include everything preceding the first left parenthesis if there is one.

.ASm

returns the access status, either R/O (read/only) or R/W (read/write), of the minidisk or SFS directory that was accessed. The .AS option is ignored in the parameter list of a PREEXIT EXEC because the minidisk or SFS directory is not yet accessed.

.CAm

returns the :CATEGORY tag value.

.CUm

returns the virtual device number used to link a minidisk, or a string containing DIR followed by the fully qualified name of the SFS directory that was accessed. For example, DIR SYSSERV:JQUSER.TASKS.

.EXm

returns the :EXIT tag value.

.FMm

returns the single character file mode letter used to access the minidisk or SFS directory, omitting the file mode extension used.

.INm

returns the :INVOKE tag value.

.LAm

returns the label of a minidisk or a hyphen for an SFS directory. The .LA option is ignored in the parameter list of a PREEXIT EXEC, because the minidisk or SFS directory is not yet accessed.

.LIm

returns the :LIST tag value.

.LSm

returns the link status, either R/O (read/only) or R/W (read/write), of the minidisk that was linked, or DIR for an SFS directory. The .LS option is ignored in the parameter list of a PREEXIT EXEC because the minidisk or SFS directory is not yet linked.

.NFm

returns the file ID of the NAMES file in which VMLINK found the nickname.

.NIm

returns the :NICK tag value.

.NOm

returns the :NODE tag value.

.OPn

returns the options passed with VMLINK. The options include everything following the first left parenthesis.

.PAn

returns the text following the PARMS option keyword.

.PRm

returns the :PRODUCT tag value, or if VMLINK was invoked with the explicit minidisk or SFS directory name, it will return user ID vdev linking details or .DIR dirname linking details

.PXm

returns the :PREEXIT tag value.

.TAm

returns the tag-value pairs for all :tagname options specified on the command invocation of VMLINK.

.TIm

returns the :TITLE tag value.

.XDn

returns all the data specified on the RETURN statement of any exit execs.

n

identifies a particular blank-delimited token in the requested string. For example, .OP3 refers to the third token in the options string. If n is not specified, the complete string is returned.

m

identifies the minidisk or SFS directory for which the information is requested. For example, .FM3 is the file mode letter of the third minidisk or SFS directory accessed by the VMLINK command. If m is not specified, 1 is assumed.

Usage Notes

1. For more information on how to customize this command, see Customizing Profiles for CMS Productivity Aids.
2. VMLINK determines how to process each disk operand in turn, by trying to establish one of these conditions as true:
   1. The NONAMES option is specified. If so, the operands are assumed to be only minidisk IDs and SFS directory names. No NAMES file is searched for nicknames.
   2. The operand is a nickname that is valid on the node. If so, VMLINK processes it using a NAMES file.
   3. The operand matches the value of a :CATEGORY tag that is valid for the node. If so, a menu of all the valid nicknames with a matching category is displayed. When an operand is determined to be a category, any linking details entered are ignored.
   4. The first word of the disk operand is .DIR. If so, VMLINK processes the operand as part of an SFS directory specification.
   5. Otherwise, VMLINK tries to process the operand as part of a minidisk ID in the form user_ID vdev.
3. VMLINK searches CMS NAMES files for nicknames. The search order and names of the NAMES files are defined in the VMLINK CONTROL file or specified on the command. For more information on the VMLINK NAMES file, see z/VM: CMS User's Guide.
4. The VMLINK control file, VMLINK CONTROL, sets local defaults for some VMLINK values. The defaults are overridden by values in a nickname entry, which in turn are overridden by operands specified with the command. For more information on the VMLINK CONTROL file, see z/VM: CMS User's Guide.
5. A disk identifier is always passed as the first argument to an exit exec. The form of the disk identifier is determined by the way the minidisk or SFS directory is specified in the command.

   Table 1. Disk Identifiers

   Specification	ID format	Disk ID
   proda191	*nickname	*PRODA191
   productc 193	*USERIDvdev	*PRODUCTC193
   .dir maint.pets	*.DIRdirname	*.DIRMAINT.PETS
   .dir .pets	*.DIRdirname	*.DIR.PETS

6. If you have called VMLINK with the NONAMES option or the NONICKtrans option, no VMLNICXT EXEC is called.

Messages and Return Codes

• DMS002E File fn ft fm not found [RC=28]
• DMS029E Invalid parameter parameter in the option option field [RC=24]
• DMS066E option1 and option2 are conflicting options [RC=24]
• DMS069E Directory dirname not accessed [RC=36]
• DMS072E Error in EXEC file fn line n - message [RC=99]
• DMS104S Error nn reading file fn ft fm from disk or directory [RC=rc]
• DMS389E Invalid operandtype: operand [RC=24]
• DMS394E Invalid option: option [RC=24]
• DMS637E Missing value for the option option [RC=24]
• DMS651E APPEND must be issued from VMLINK [RC=40]
• DMS739W No autolinks are set
• DMS926E Command is only valid on a display terminal [RC=88]
• DMS1227E No {file mode | virtual device address} is available to {access | link} {nickname minidisk | directory} [RC=40]
• DMS1233E Invalid use of option option [RC=24]
• DMS2059E USERID VDEV must be specified with the NONAMES option [RC=24]
• DMS2059E .DIR DIRNAME must be specified with the NONAMES option [RC=24]
• DMS2060I {nickname|user ID vdev|directory_name} {linked|accessed} [vdev|link_mode] as [vdev|link_mode] filemode fm [RC=0]
• DMS2061I description [detached | released] [RC=0]
• DMS2062I NAMEFIND search results for file: fn ft fm for nickname: nickname [RC=0]
• DMS2064I Autolink [status updated|removed] for nickname [RC=0]
• DMS2064W Autolink not found for nickname [RC=4]
• DMS2064E Autolink update failed RC=rc for nickname [RC=rc]
• DMS2065E Minidisk virtual address vdev already defined [RC=40]
• DMS2066E [Virtual address | Link mode lm] is not valid [RC=24]
• DMS2067E Unknown [ disk nickname (nickname) | USER ID (user ID) | category (category) ] [RC=32]
• DMS2068E Disk nickname (nickname) not valid on this node id [RC=32]
• DMS2069E No NAMES file(s) found to search for nickname (nickname) [RC=28]
• DMS2070E POP data not available [RC=40]
• DMS2071E The MODE0 option cannot be used because the ACCESSM0 command is not available [RC=40]
• DMS2072E No nickname was specified with the QUERY option [RC=24]
• DMS2073W Warning: Duplicate autolink filemode: fm
• DMS2074W Warning: Disk nickname will be released
• DMS2075W Disk is still accessed {R/W | R/O}. Use the {READ | WRITE} option to {detach | release} [RC=4]
• DMS2076W There was no {R/O | R/W} {disk | directory} to {detach | release} [RC=4]
• DMS2077E FILELIST not done. No disk was accessed or first disk was released [RC=32]
• DMS2884E Unexpected return code rc {on command command | from exit exit} [RC=rc]
• DMS2923E Missing right parenthesis [RC=24]

Additional system messages may be issued by this command. The reasons for these messages and their location are: