CA MIA Statements and Commands › (MIA) USERDATA Command—Populate Device Data Field

(MIA) USERDATA Command—Populate Device Data Field

The USERDATA command lets you put data into the user data field for a specific device. This command is used most often to pass information to the CA MIA application program interface (API). GTAF propagates the data to all systems. You can then retrieve the data by invoking the application program interface, or display it by issuing the DISPLAY GLOBALUNITS command.

Scope: Local

This command has the following format:

USERDATA	 device text

device

Specifies the local or global name of a GTAF-managed device.

text

Defines the one- to eight-byte character string that you want to put into the user data field associated with the device.

Notes:

• You can specify this text in either character or hexadecimal format. For example, you can specify A123 or X'C1F1F2F3'.
• If you want to include spaces in a character string, then place the entire string between single quotation marks.
• The length of the CA MIA user data field is defined in bytes, and two hexadecimal positions are equal to one byte of data; therefore, an odd number of hexadecimal positions is ambiguous if it is entered as text to be moved into a data field defined in terms of bytes.

Default: The user data field is initialized to nulls (X'00').

Usage Notes: USERDATA Command

• You determine how the USERDATA field is updated based on the value specified in the SETOPTION USERDATA command. FULL causes the entire data field to be updated, while PARTIAL causes only affected bits to be updated.
• The SETOPTION TPCF USERDATA command also gives you control over whether the MIM2069 message is issued after successful completion of the USERDATA command processing. You may specify YES to receive the MIM2069 message after successful completion of the USERDATA command. Otherwise, specify NO if you do not want to receive this message.
• The maximum number of bytes is eight. If the data you input is less than the maximum length of the user data field, then GTAF left-justifies the data in the field and pads the remainder of the field to the right with nulls (X'00'). GTAF does not verify that the length of the user data field is the same on all systems.
• In cases where hexadecimal text is entered with an odd number of positions, the USERDATA field is filled to the left with one hexadecimal digit '0' (one half-byte of nulls).

  For example:

• You can display the user data field by issuing the DISPLAY GLOBALUNITS command if the USERDATA operand on the SETOPTION GLOBALDISPLAY is set to YES. In this display, nulls and other non-EBCDIC characters are displayed as dots, except that a USERDATA field of nulls is displayed as blank.
• You can retrieve data from the user data field by invoking the application program interface (module name MIMAPI1).
• User data is not restricted to EBCDIC codes, but if you use DISPLAY GLOBALUNITS to view the user data, non-displayable characters are translated to dots for the display. An exception is made when user data is in its initial state of all nulls (X'00'). In this case, the user data field remains blank in the DISPLAY GLOBALUNITS display.

• The USERDATA command can be specified in the CMNDS MIM or SYNCH MIM files. You also can issue this command from a console.
• The USERDATA command is privileged and can be specified only in the CMNDS MIM or SYNCH MIM files, the service virtual machine console, or a CMS user ID with OPER authorization.

Examples: USERDATA Command

• To enter the characters CLASSA into the user data field associated with device 01A0, issue the following command:

  USERDATA 01A0 CLASSA
  

• To input this same data in hexadecimal format, issue the following command:

  USERDATA 01A0 X'C3D3C1E2E2C1'
  

VARY Command-Change Status of Devices

The VARY command lets you change the status of devices that are being managed by the CA MIA component.

This command has the following format:

VARY (devices), {{AVAILABLE|NOTAVAILABLE} [{EXTERNAL|GLOBAL|[LOCAL|sysid}] |
                {CPON|CPOFF} |
                {DEDICATED|NOTDEDICATED} |
                {NOJOB|J=userid} [{GLOBAL | LOCAL}] |
                {NOTOVERGENNED|OVERGENNED} [{EXTERNAL|GLOBAL|[LOCAL|[sysid}] |
                {ONLINE|OFFLINE} [{EXTERNAL|GLOBAL|[LOCAL|[sysid}] |
                PREFERENCE={value|NONE} }

AVAILABLE

Releases a not-available device and varies that device online. This makes the device available for allocation.

The VARY AVAILABLE command also wakes up the jobs waiting in allocation recovery for a device.

You can specify the following operands:

EXTERNAL

Modifies device status on all external systems (that is, on all systems except the local system).

GLOBAL

Modifies device status on all systems.

LOCAL

Modifies device status on the local system.

sysid

Represents the ID of a system to which you want to direct this VARY command.

The system ID represents the full system name or alias that is assigned to the system using the DEFSYS statement or the one- or two-digit index number of the system. If CA MIM for z/OS cannot find a match between the value you specify for sysid and any known system, then it issues message MIM2063 and ignores the VARY command.

Notes:

• FORCE can only be used with NOTAVAILABLE. By default, GTAF uses the scope value that is specified for the VARYSCOPE operand on the SETOPTION command.
• You can use the abbreviation AVL for this operand.
• Only use the GLOBAL operand on VARY commands coded in the MIMCMNDS or MIMSYNCH parmlib members when the VARY commands are directed to a single system. Use the IFSYS and ENDIF statements to direct commands to specific systems.

CPON

Varies the device online and reserves it for CP use on the local system. This makes the device unavailable for allocation on external systems and unavailable for use by CMS users on the local system.

CPOFF

Releases a device reserved for CP use. This makes the device available for allocation on any system.

DEDICATED

Dedicates the device to jobs on the local system and varies the device offline on all external systems. This makes the device unavailable for allocation on external systems unless there is no other suitable device.

devices

Identifies the device for which you are making a status change. The device is identified by its three- or four-character global name. Enter a single device name, a range of device names, or a list of device names. Specify a range of tape drives by typing two global names separated by a hyphen (for example, 03A0-03A2).

A list of tape drives is specified as two or more global names separated by a comma or space. A list always must be enclosed in parentheses. A list may include a range of drives. For example,

03A0
03A0-03A2
(03A0,03A1,03A2)
(03A0 03A1 03A2)
(03A0-03A2,07E0-07E1)

Note: The devices specified on a VARY RANGE command are presented to the operating system for processing as individual VARY Device requests in ASCENDING device address order, regardless of the order in which device address ranges are specified on the VARY RANGE command.

If you want a specific sequence of VARY command processing, code individual VARY or VARY RANGE commands to achieve the desired VARY completion sequence.

A pending VARY requests can be purged with the VARY PURGE parameter.

LOCAL

Modifies device status on the local system.

NOJOB

Releases a reserved device.

EXTERNAL

This scope parameter modifies device status on all external systems (that is, on all systems except the local system).

GLOBAL

This scope parameter modifies device status on all systems. CA recommends that you do not use the GLOBAL parameter when specifying this command in the CMNDS MIM or SYNCH MIM files unless you are directing the command to a single system (using IFSYS and ENDIF statements).

J=userid

This reserves the device for the job with the name you specify here. The J parameter interacts with the JOB parameter used on z/OS systems. When you specify J=userid on a z/VM system, z/OS systems will display JOB=userid as if the user ID is equivalent to a job.

You can enter a complete user ID or the leading characters of an ID followed by an asterisk (*) wildcard character. The wildcard character may not be specified in the first position of the user ID, and no characters may be specified after the wildcard character. You can use the GLOBAL and LOCAL scope values.

NOTAVAILABLE

Assigns not-available status to the device and varies the device offline. This makes that device unavailable for allocation unless no other device is available.

You can specify the following operands for NOTAVAILABLE:

EXTERNAL

Modifies device status on all external systems (that is, on all systems except the local system).

FORCE

Takes a device that is in use on another system offline on the local system. If the device is allocated externally, then it is taken offline locally and given a status of not available. If the device is online but not allocated, then it is varied offline and also given a status of not available. To bring the device back online after issuing a VARY NOTAVL FORCE command, issue a VARY AVAILABLE command.

GLOBAL

Modifies device status on all systems.

LOCAL

Modifies device status on the local system.

sysid

Represents the ID of a system to which you want to direct this VARY command.

The system ID represents the full system name or alias that is assigned to the system using the DEFSYS statement or the one- or two-digit index number of the system. If CA MIM cannot find a match between the value you specify for sysid and any known system, then it issues message MIM2063 and ignores the VARY command.

Notes

• The FORCE parameter can only be used with NOTAVAILABLE. By default, GTAF uses the scope value that is specified for the VARYSCOPE operand on the SETOPTION command.
• You can use the abbreviation NOTAVL for this operand.
• Only use the GLOBAL operand on VARY commands coded in the MIMCMNDS or MIMSYNCH parmlib members when the VARY commands are directed to a single system. Use the IFSYS and ENDIF statements to direct commands to specific systems.

NOTDEDICATED

Releases a dedicated device and varies that device online to all systems. This makes that device available for allocation on any system.

NOTOVERGENNED

Returns a device from the overgenned status to normal status and varies the device online. The following operands limit the scope of this parameter:

EXTERNAL

Modifies device status on all external systems (that is, on all systems except the local system).

GLOBAL

Modifies device status on all systems.

LOCAL

Modifies device status on the local system.

sysid

Represents the ID of a system to which you want to direct this VARY command.

The system ID represents the full system name or alias that is assigned to the system using the DEFSYS statement or the one- or two-digit index number of the system. If CA MIM cannot find a match between the value you specify for sysid and any known system, then it issues message MIM2063 and ignores the VARY command.

You can use the abbreviation NOTOVG for this operand.

Default: GTAF uses the defined value that is specified for the VARYSCOPE operand on the SETOPTION command.

OFFLINE

Varies the device offline. The following operands limit the scope of this parameter:

EXTERNAL

Modifies device status on all external systems (that is, on all systems except the local system).

GLOBAL

Modifies device status on all systems.

LOCAL

Modifies device status on the local system.

sysid

Represents the ID of a system to which you want to direct this VARY command.

The system ID represents the full system name or alias that is assigned to the system using the DEFSYS statement or the one- or two-digit index number of the system. If CA MIM cannot find a match between the value you specify for sysid and any known system, then it issues message MIM2063 and ignores the VARY command.

Default: GTAF uses the scope value that is specified for the VARYSCOPE operand on the SETOPTION command.

ONLINE

Varies the device online. The following operands limit the scope of this parameter:

EXTERNAL

Modifies device status on all external systems (that is, on all systems except the local system).

GLOBAL

Modifies device status on all systems.

LOCAL

Modifies device status on the local system.

sysid

Represents the ID of a system to which you want to direct this VARY command.

The system ID represents the full system name or alias that is assigned to the system using the DEFSYS statement or the one- or two-digit index number of the system. If CA MIM for z/OS cannot find a match between the value you specify for sysid and any known system, then it issues message MIM2063 and ignores the VARY command.

Default: GTAF uses the scope value that is specified for the VARYSCOPE operand on the SETOPTION command.

OVERGENNED

Assigns overgenned status to a device and varies the device offline. You can use the abbreviation OVG for this operand.

You can specify following operands to indicate the scope of the status change:

EXTERNAL

Modifies device status on all external systems (that is, on all systems except the local system).

GLOBAL

Modifies device status on all systems.

LOCAL

Modifies device status on the local system.

sysid

Represents the ID of a system to which you want to direct this VARY command.

The system ID represents the full system name or alias that is assigned to the system using the DEFSYS statement or the one- or two-digit index number of the system. If CA MIM cannot find a match between the value you specify for sysid and any known system, then it issues message MIM2063 and ignores the VARY command.

Default: GTAF uses the scope value that is specified for the VARYSCOPE operand on the SETOPTION command.

• The VARY command can be specified only in the CMNDS MIM or SYNCH MIM files, issued from the service virtual machine console, or by CMS users with OPER authorization.
• The VARY command will not influence the availability of a device when the CP ATTACH command is used directly. The only exception is in the case where a device has been varied online or offline.
• You cannot use the scope parameter when specifying these parameters:

  CPON
  CPOFF
  DEDICATED
  NOTDEDICATE
  PREFERENCE

• Use the LOCAL scope parameter if you issue VARY from CMNDS MIM or SYNCH MIM files or within the z/OS equivalent members. If VARY is performed with GLOBAL scope within these files, a flood of repetitious VARY commands can be propagated throughout the MIMplex as each system synchronizes. The flooding effect is especially noticeable when the VARY commands are issued from a z/OS system because multiple z/OS systems often share the same CMNDS and SYNCH members.
• VARY commands issued from within CMNDS MIM are queued for execution after synchronization occurs. CA recommends placing VARY commands in SYNCH, rather than in CMNDS.

PREFERENCE

Specifies the preference value you are assigning to this device (the higher the preference value, the more preferred the device). TPCF assigns this preference value on the local system only. You can specify a value from 1 to 255, or NONE. NONE causes device preferencing to not be done for the specified devices.

Default: PREFERENCE=NONE

Note: When NONE is specified, no preference value will be displayed.

Examples: VARY Command

• To reserve tape drive 1A2 for user ID DSIAZ11 on the local system, issue the following command:

  MI VARY 1A2 J=DSIAZ11
  

• To dedicate tape drives 1A3, 1A4, and 1A5 to the local system, issue the following command:

  MI VARY (1A3-1A5) DEDICATED
  

• To assign a preference value of 10 on the local system to device 1A4, issue the following command:

  MI VARY 1A4 PREFERENCE=10
  

• To make tape devices 1A5 and 3B5 unavailable to system SYSA, issue the following command:

  MI VARY (1A5,3B5) NOTAVAILABLE SYSA
  

Note: In these examples, the MI prefix is shown to distinguish the MI VARY command from the CP VARY command. These example commands could also be issued using the SMSG command. Other examples in this section do not show the MI prefix.