Utilities and Other Interfaces › The Application Program Interface › Call the MIMAPI1 Module › How You Define an Output Data Area for the MIMAPI1 Module

How You Define an Output Data Area for the MIMAPI1 Module

The MIMAPI1 module returns information to an output data area that you previously defined. Define the data area as follows:

1. Begin the data area on a double-word boundary.
2. Consider the addressing mode of the calling program when you are using the MIMAPI1 interface on a z/OS system. If the program is running in 31-bit mode, then you can define the data area anywhere. If the program is running in 24-bit mode, then define the data area below the 16 MB line.
3. Member API1CPY1 of data set CAI.CBTDMAC contains a DSECT that maps this output data area. The minimum length of the area is the length of the DSECT in the API1CPY1 member.

Entry Environment:

Task mode, key 8, AMODE 31 or AMODE 24, RMODE 24 or RMODE ANY.
The entry environment is preserved and restored upon return.

Register Usage at Entry:

R1

Contains the address of the parameter list, in the following format:

+0 PARML1

Address of the local or global unit name of the device for which you wish to obtain information. If PARMRLSE=PARMR41 (X'040100') or higher, then PARML1 must point to a right-justified 4-character field. For example, to request a match on device 380, PARML1 points to C' 380', where a blank space precedes 380.

+4 PARML2

Contains the address of the receiving area. The INFOAREA DSECT in the API1CPY1 member defines the format for this area.

+8 PARMLA

This contains additional processing instructions. You can specify the following values here:

80 PARMLATM–This runs the MIMAPI1 module in protected mode. Use of this option involves an amount of additional overhead on each request.

40 PARMLARC–When running in the protected mode, this records abend information in the SYS1.LOGREC data set.

20 PARMR20–The format of the returned data has changed for CA MIA Release 4.0. The API does not support requests for data format for releases prior to 4.0. You must convert your API calls to use the new parameter lists.

10 PARMMULT–This is a multiple device request that tells MIMAPI1 to obtain the number of devices to return as specified in the PARMNREQ field.

08 PARMRLSF–The release number is in PARMRLSE.

0F PARMLARS–Reserved flags.

+9 PARMRSV1

Reserved.

+A PARMNREQ

This is where you specify how many devices should be returned.

+C PARMNOUT

This field indicates how many devices actually were returned.

+E PARMRLSE

This field shows the release number format (right justified).

40 PARMR40–Release 4.0 format.

040100 PARMR41–Release 4.1 format.

040200 PARMR420–Current format.

+12 PARMRSV2–Reserved.

+14 PARMRSV3–Reserved.

R13

Contains the address of the 18-word save area.

R14

Contains the return address of the invoking program.

R15

Contains the address of the interface module.

All other registers are undefined.

Return Values in the Data Area:

+0 INFOXTRN

Contains the four-byte global name of the device.

+4 INFOUNIT

Contains the local UCB name (right-justified) from the UCB on this z/OS system.

+8 INFOVSER

Contains the volser of the volume mounted on the device.

+E INFOPREF

Contains the preference value assigned to the device in EBCDIC. Valid values are C'0001' through C'0255'. If PREF=NONE, the value is C' '. The default value is C' '.

+12 INFOS1

Contains the TPCF preferencing status assigned to the device. One or more of these values is shown:

80 INFOS1HE

The device is dedicated to the local system.

40 INFOS1TH

The device is dedicated to an external system.

20 INFOS1NA

The device has not-available status on the local system.

10 INFOS1OG

The device has overgenned status on the local system.

+13 INFOS2

Contains the device types for this system:

80 INFT3420

Indicates that the device type is 3420.

40 INFT3480

Indicates that the device type is 3480.

20 INFTACL

Indicates that the device has Automatic Cartridge Loader (ACL) installed.

08 INFTACLA

Indicates that the device has ACL installed and activated.

10 INFTIDRC

Indicates that the device type is 3480/3490 with IDRC.

04 INFT3490

Indicates that the device type is 3490.

02 INFT3495

Indicates that the device type is 3495.

01 INFT3590

Indicates that the device type is 3590.

+14 INFOMASK

Contains the job name or jobmask, if the device is reserved. If it is not reserved, then the value is CL8' '.

+1C INFOMLEN

Contains the machine length of the job name or jobmask (0-7).

+1D INFOMSYS

This identifies the systems on which the device is reserved. If it is reserved on all systems, then the value is CL8'ALL'. If it is not reserved, then the value is CL8' '.

+25 INFOALOC

If this device is allocated, then this contains the job name the device is allocated to. If the device is not allocated, then this field contains the value CL8' '.

+2D INFOUSRD

This contains 8 bytes of user data information or nulls.

+35 INFOUSRL

Contains the length of the user data returned in the previous field.

+36 INFOINDX

Contains the index of the local system in the table of systems that is returned in the field at +50. The index is 0-based. The value ranges from 0-31.

+37 INFORSV1

Reserved.

+38 INFOKNOW

Contains the mask of known systems.

+3C INFOFREE

Contains the mask of freed systems.

+40 INFOHNAM

Contains the Autopath host name of the device (right justified), or null if not Autopath-managed.

+44 INFORSV2

Reserved.

System name and flag bytes from each system. These contain the eight-byte system name and two-byte device status for each system. This information is shown once per system. When you are running fewer than 32 systems, nulls are inserted for the entries for undefined systems. The flag byte definitions for the two-byte device status are shown next.

Return Values in the Data Area:

+50 INFOSYS0

CL8' ',XL2'00'

+5A INFOSYS1

CL8' ',XL2'00'

+64 INFOSYS2

CL8' ',XL2'00'

+6E INFOSYS3

CL8' ',XL2'00'

+78 INFOSYS4

CL8' ',XL2'00'

+82 INFOSYS5

CL8' ',XL2'00'

+8C INFOSYS6

CL8' ',XL2'00'

+96 INFOSYS7

CL8' ',XL2'00'

+A0 INFOSYS8

CL8' ',XL2'00'

+AA INFOSYS9

CL8' ',XL2'00'

+B4 INFOSYSA

CL8' ',XL2'00'

+BE INFOSYSB

CL8' ',XL2'00'

+C8 INFOSYSC

CL8' ',XL2'00'

+D2 INFOSYSD

CL8' ',XL2'00'

+DC INFOSYSE

CL8' ',XL2'00'

+E6 INFOSYSF

CL8' ',XL2'00'

+F0 INFOSYT0

CL8' ',XL2'00'

+FA INFOSYT1

CL8' ',XL2'00'

+104 INFOSYT2

CL8' ',XL2'00'

+10E INFOSYT3

CL8' ',XL2'00'

+118 INFOSYT4

CL8' ',XL2'00'

+122 INFOSYT5

CL8' ',XL2'00'

+12C INFOSYT6

CL8' ',XL2'00'

+136 INFOSYT7

CL8' ',XL2'00'

+140 INFOSYT8

CL8' ',XL2'00'

+14A INFOSYT9

CL8' ',XL2'00'

+154 INFOSYTA

CL8' ',XL2'00'

+15E INFOSYTB

CL8' ',XL2'00'

+168 INFOSYTC

CL8' ',XL2'00'

+172 INFOSYTD

CL8' ',XL2'00'

+17C INFOSYTE

CL8' ',XL2'00'

+186 INFOSYTF

CL8' ', XL2'00'

Definition of flag bytes from each system.

First flag byte:

80 INFOF1DH

The device is dedicated to this system.

40 INFOF1DT

The device is dedicated to another system.

20 INFOF1NA

The device has not-available status on this system.

10 INFOF1OV

The device has overgenned status on this system.

08 INFOF1AL

The device is allocated on this system.

04 INFOF1OL

The device is online to this system.

02 INFOF1MP

The device has a mount pending on this system.

01 INFOF1JR

The device is reserved for a job or group of jobs on this system.

Second flag byte:

80 INFOF2PO

The device is pending offline on this system.

7F INFOF2FF

Reserved flags.

Return Code, Register 15:

X'00' CODEGOOD

This indicates that the MIMAPI1 module has placed device information in the specified data area.

X'04' CODENMAT

This indicates that CA MIA is not managing the device.

X'08' CODENCPT

This indicates that the data format you requested is incompatible with the release of CA MIA that you are running. The MIM1API1 module returns as much data to the user as is possible.

X'0C' CODENACT

This indicates that CA MIA is not running or is not synchronized.

X'10' CODENMAN

This indicates that the MIMAPI1 module cannot obtain the GETMAIN storage needed to create the ESTAE exit parameter list.

Note: This return code appears only in test mode.

X'14' CODENEST

This indicates that the MIMAPI1 module cannot establish an ESTAE exit.

Note: This return code appears only in test mode.

X'18' CODEABND

This indicates that the MIMAPI1 module encountered an abend, probably due to receiving a system abend 0C4 when moving data to the specified data area.

Note: This return code appears only in test mode.

Note: ALL registers (except 0, 1, and 15) are restored upon return.