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.

• You can specify the USERDATA command in the MIMCMDS or MIMSYNCH member of the MIMCMDS data set. You can also issue this command from a console.
• You must be authorized to issue system commands to issue the USERDATA command. TSO users generally are not authorized to issue system control commands.

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'