GETVCE (Get Volume Characteristics) Macro

Format

Requirements for the caller

AMODE:

24 or 31

RMODE:

ANY

ASC Mode:

Primary

Parameters

AREA=name1 | (S,name1) | (r1)

Specifies the address of an area where you want the volume characteristics to be stored. For the format of this area, see GETVCE Output.

DEVICE=SYSxxx | X'cuu' | DASD

Identifies the device whose volume characteristics are to be returned. The specification can refer to a logical unit (SYSxxx) or to a physical unit (cuu). DASD indicates that the cuu and VOLID for all DASDs is to be returned.

VOLID=name2 | (S,name2 | (r2)

Specifies the address of a 6-byte field that contains the volume serial number of the device whose volume characteristics are to be returned. When register notation is used, the register must also point to a 6-byte field.

If duplicate volume serial numbers are present in the system, the first one found by GETVCE is saved and returned if the associated device is not DOWN or if all the associated devices are DOWN. In all other cases the first device which is not DOWN is returned.

The VOLID can be qualified by the DEVTYPE operand which further limits the search.

DEVTYPE=name3 | (S,name3) | (r3)

Specifies the address of a 1-byte field that contains the device type code of the device to be returned. Specified with VOLID, DEVTYPE returns volume and device information for the volume with the matching volume serial number and device type (for example, 3380).

LOGUNIT=name4 | (S,name4) | (r4)

Specifies the address of a 2-byte field that contains the logical unit name of the device to be returned.

CHNUNIT=name5 | (S,name5) | (r5)

Specifies the address of a 2-byte field that contains the physical unit address (channel, unit) of the device to be returned.

CLASS=TAPE | DASD | ANY

Indicates the device class for which the request is to be made. Default is DASD, ANY includes TAPE and DASD.

LENGTH=n

Specifies the length of the data to be placed into the AREA field. The AREA field is initially cleared for this length before the requested information is moved in. Default is the maximum defined length.

MFG=name6 | (S,name6) | (r6)

Specifies the address of a dynamic storage area that is to be used for parameter list construction for re-entrant programs.

REQUEST=TRKBAL | TRKCAP

TRKBAL requests the track balance to be returned, that is, the number of remaining bytes on a track of the specified DASD. The output is returned in register 0.

Balance calculation determines the amount of physical data fitting on a track if a record were to be written or deleted. No actual record is being written or deleted; the calculation merely gives the number of bytes left on a track if such an operation had taken place. The operation itself is indicated in the OPTION operand: REMOVE indicates that the record is to be deleted. If OPTION has been omitted, the record is to be written.

You can provide the track balance yourself (in the BALANCE operand), which is the balance that is true before the operation indicated by REMOVE takes place. The value that is returned by GETVCE will then be the balance after the operation took place.

In the following example, the record is assumed to be removed (OPTION=REMOVE), the record to be removed is record no. 3 (RECNO=), and the balance is provided by the user (BALANCE=):

|<-------------Total usable space on track----------->|
<######>         =  Record size
<%%%%...%%%>     =  User-provided balance
<====...=====>   =  New balance, returned by GETVCE
 
Situation on entry to GETVCE:
|<######><######><######><%%%% Given by user %%%%%%%%>|
 
Situation on exit:
|<######><######><====== Returned by GETVCE =========>|

In the next example, the record is assumed to be written (no OPTION=), the record to be written is record no. 3 (RECNO=), and no balance is provided by the user:

Situation on entry to GETVCE:
|<######><######><...................................>|
 
Situation on exit:
|<######><######><######><===========================>|

TRKCAP requests the track capacity to be returned, that is, the number of whole records that fit either into a user-supplied track balance (BALANCE=) or into the system-calculated track balance (remainder of the track). The output is returned in register 0.

The calculated value depends on the REMOVE option: If the option is not set, GETVCE takes the user-provided balance without subtracting the record 's size from this value. (This is different from the above balance calculation, where the record size was subtracted.) This approach is useful if you want to know how many records would fit into a given balance.

DATALEN=name7 | (S,name7) | (r7)

Specifies the address of a 2-byte field containing the length of one fixed-length data record. This field is processed as an unsigned binary value.

KEYLEN=name8 | (S,name8) | (r8)

Specifies the address of a 1-byte field containing the key length of one fixed-length data record. This field is processed as an unsigned binary value. If non-keyed records are processed, this byte must either be set to zero or the operand must be omitted.

RECNO=name9 | (S,name9) | (r9)

Specifies the address of a 1-byte field containing the record number. A record number of zero (which is also the default) results in the maximum track balance being returned to the user or being used for track capacity calculations.

BALANCE=name10 | (S,name10) | (r10)

Specifies the address of a 2-byte field containing the track balance that is to be used for calculation. This balance field is processed as an unsigned binary value. If the balance is not known, this operand must be omitted.

OPTION=REMOVE | MAXSIZE

REMOVE indicates that the given record with the specified DATALEN and KEYLEN is assumed to be removed from the track by the user. GETVCE processing calculates and increment the track balance or track capacity. If the user also provided a balance, it must always equal the number of bytes available on the track before the record was removed.

If the operand is omitted, the given record is assumed to be written on the track of the specified device.

MAXSIZE specifies that the length of the largest data record that would still fit onto the remainder of the track is to be returned (key length has already been taken into account).

If the record to be written does not fit onto the track, return code X'24' is set, where the returned value is the amount of user data that would still fit onto the remainder of the track if the record is not written.

GETVCE Output

The output field pointed to by AREA is initially cleared for the specified length (LENGTH=) before the requested information is moved in. The output is described by a DSECT generated by the macro AVRLIST DSECT=YES,DEVICE=YES (Refer to AVRLIST (Map GETVCE) Macro and DCTENTRY (Map GETVCE) Macro for details).

For REQUEST=TRKCAP, register 0 contains the number of whole records that fit on the remainder of the track (input track balance).

For REQUEST=TRKBAL, register 0 contains the updated track balance if a new record fits or an old record is removed. If a whole record would not fit (R15=36) and MAXSIZE was requested, register 0 is set to the maximum number of data bytes that would fit onto the remainder of the track (key bytes have already been taken care of). If a whole record would not fit and MAXSIZE was not specified, register 0 is set to zero.

Return Codes in Register 15

0

Successful completion.

4

Successful completion, but some data is not valid.

8

The volume that is specified is not mounted, or the logical unit that is specified is not assigned, or the specified unit is not included in the system.

12

The logical unit that is specified is assigned IGNORE.

16

The device is not operational.

20

The parameter list is invalid (for example, the logical unit number is too high).

24

The given logical unit or device does not belong to the class specified in the CLASS operand.

28

The device is not ready.

36

For REQUEST=TRKBAL or TRKCAP only: The input balance is not sufficient to accommodate a record of the specified key and data length. MAXSIZE was specified and at least one byte of data could be written. Register 0 returns the maximum number of data bytes that would fit onto the remainder of the track.