Reference Guide › User Exit Reference › FORMAT User Exit

FORMAT User Exit

The FORMAT user exit is called each time a minidisk needs to be formatted, allowing you to either:

• Format the minidisk according to site‑determined requirements
• Or, respond back to CA VM:Director to have it use the default formatting utility program.

  FORMAT userid userid2 vaddr acigroup link_vaddr fmtmode fmtblksize
  

  fmtlabel fmttype macroname fmtcmd cmdtarget
  

Definitions

userid

The user ID running the command requesting minidisk formatting.

Userid2

The owning user ID of the minidisk being formatted.

vaddr

The virtual address of the minidisk owned by userid2.

acigroup

The ACI group of userid2. If userid2 does not have an ACI group or if the ACI group is not available, an asterisk (*) is specified.

link_vaddr

The virtual address of the link to the disk being formatted.

fmtmode

The CMS access mode to be used on the format command.

fmtblksize

The block size to be used on the format command. Expected values are 512, 1024, 2048, 4096, 1K, 2K, or 4K.

fmtlabel

The label to be used on the format command.

fmttype

Indicates if the disk being formatted is a new area (ADD) or is being deleted (DEL).

macroname

The caller of the FORMATMD macro, which calls the FORMAT user exit.

fmtcmd

Indicates the format command that CA VM:Director would use, as specified on the CA VM:Director ALTERNAT record in the PRODUCT CONFIG file.

Note: For more information, see ALTERNAT Record.

cmdtarget

Indicates the CA VM:Director primitive to use to issue your commands. Valid entries for this field are USER or SERVANT.

Description

Because of the requirements of issuing macro primitives, the FORMAT user exit cannot be written in Assembler. It must be coded in REXX or EXEC2.

When moving a minidisk from one location to another and the device type, block size, or number of cylinders of the disk has not changed, CA VM:Director uses DDR to move the minidisk to its new location instead of using the FORMAT and COPYFILE commands. This means that only the source minidisk is formatted; therefore, the FORMAT user exit is called only for the source minidisk.

The FORMAT user exit uses CA VM:Director macro primitives, commands that are issued within the user exit, to communicate with the user or servant user ID. The user or servant user ID is the user ID where the minidisk and the SFS directory are accessed.

The CA VM:Director macro primitives that are most likely to be used are:

• USER EXECUTE or SERVANT EXECUTE—Issues a command on the user or servant virtual machine. The command text arguments that follow are issued on the indicated machine using CMSCALL.
• USER STACK or SERVANT STACK—Places data that you will need later on, such as for a subsequent command, on the user or servant virtual machine program stack. The arguments that follow are stacked in LIFO order on the appropriate program stack.
• USER READ or SERVANT READ—Causes the data that exists on the user or servant virtual machine stack to be read to storage on the user or servant virtual machine.

To use any of these primitives, precede it with the token TEST. This token allows the primitive to pass a nonzero return code back to the exit.

The sample (prototype) user exit contains examples of the use of these primitives.

Return Codes

The following table describes the return codes:

Macros

The FORMAT user exit is called by the VMXFMT00 macro, whose optimized macro name is FORMATMD, under the following circumstances: