The MEDIA INITIALIZE command initializes the medium and writes a tape label and an end of tape mark at the beginning of the reel. It performs in the same way as the VMS INITIALIZE command. The ownership and protection settings are picked up from the MEDIA DATABASE.⁷ The MEDIA INITIALIZE command requires write and initialize access to the medium and uses the format:

$ MEDIA [MEDIUM_NAME] INITIALIZE/QUALIFIERS

Please see the Reference Manual for a complete list of qualifiers.

11.4.3 The MEDIA MOUNT command

The MEDIA MOUNT command mounts the medium on the allocated drive. It is equivalent to the VMS MOUNT command and requires read access to the medium. The command format is:

$MEDIA [MEDIUM_NAME] MOUNT/QUALIFIERS

Please see the Reference Manual for a list of qualifiers that can be used.

11.4.4 The MEDIA DISMOUNT command

The MEDIA DISMOUNT command dismounts a medium and is equivalent to the VMS DISMOUNT command. It is used in the format:

$MEDIA [MEDIUM_NAME] DISMOUNT/QUALIFIERS

Please see the Reference Manual for a list of qualifiers that can be used.

11.4.5 The MEDIA UPDATE command

The MEDIA UPDATE command updates the on-line directory. It extracts all the directory information from a medium and adds it to the on-line directory information. Write access to the medium is required. The command format is:

$ MEDIA [MEDIUM_NAME] UPDATE/QUALIFIERS

Please see the Reference Manual for a complete list of qualifiers.

11.4.6 The MEDIA DEALLOCATE command

The MEDIA DEALLOCATE command deallocates the drive. This releases the drive back to the system. The command format is:

$ MEDIA [MEDIUM_NAME] DEALLOCATE

11.4.7 Example of device commands

$ MEDIA ABC001 ALLOCATE $ MEDIA MOUNT $ DO YOUR STUFF $ MEDIA DISMOUNT $ MEDIA DEALLOCATE

All media job commands create this sequence automatically. All that is needed is that you provide the "do your stuff" command. For example, the following job command will create the above command procedure and submit it into an appropriate queue for execution.

$ MEDIA ABC001 $ DO YOUR STUFF

11.5 Using command files

All the supplied commands are designed to be similar to VMS commands and can be used in command files in any fashion that is appropriate.

MEDIA Job commands GENERATE batch command files that are then submitted into the appropriate queue. A similar approach is used in the BCKMGR program to activate a job definition. The commands in these files use certain symbols and logical names to coordinate and control the job execution. These same logical names and symbols can be used inside the user supplied commands. All such symbols are placed in the global symbol table.

11.5.1 Medium allocations

Any command that allocates a new medium from the available pool will define the DCL symbol MEDIA_EXT to contain the name of the allocated medium. This can be very useful when using this in a command procedure, to allocate a medium and then issue a series of commands to it. For example:

$MEDIA UNKNOWN/TYPE=TAPE SET/COMMENT- ="TEST TAPE"/NOLOG $MEDIA 'MEDIA_EXT' SET/LABEL=ANSI/UPDATE=SIZER $MEDIA 'MEDIA_EXT'/NOLOG $COPY *.FOR MEDIA: $SYNCHRONIZE/ENTRY='MEDIA_ENTRY_NUMBER'

In this example, a new TAPE is allocated, some of the flag settings are changed, and then a job is created to copy some files to the new tape. All job commands after a job is successfully queued, define the DCL symbol MEDIA_ENTRY_NUMBER to contain the job number of the job that was created. The SYNCHRONIZE command will then wait for the completion of that copy operation.

One useful variation on this is to use the user defined name. The same command procedure would then appear as follows:

$MEDIA MY_SPECIAL_DATA/NEW/TYPE=TAPE SET/COMMENT ="TEST TAPE"/NOLOG $MEDIA MY_SPECIAL_DATA SET/LABEL=ANSI/UPDATE=SIZER $MEDIA MY_SPECIAL_DATA/NOLOG $COPY *.FOR MEDIA: $SYNCHRONIZE/ENTRY='MEDIA_ENTRY_NUMBER'

11.5.2 MEDIA Jobs

All the device commands maintain a medium name value in memory. This value is actually the DCL symbol MEDIA_EXT. This name will be used in any command where the medium name is left out. This is very useful in the following sequence:

$ MEDIA ABC001 ALLOCATE $ MEDIA MOUNT $ DO YOUR STUFF $ MEDIA DISMOUNT $ MEDIA DEALLOCATE

All MEDIA job commands create this type of sequence automatically. All that is needed is that you provide the "do your stuff" command. For example the following job command will create the above command procedure and submit it into an appropriate queue for execution. ⁸

$ MEDIA ABC001 $DO YOUR STUFF

The device commands are interrelated and must be executed in a certain sequence.

The required order is listed in Table 11-5.

Table 11-5 Required order of device commands

Command	Function
ALLOCATE	ALLOCATE
[INITIALIZE]	UPDATE
MOUNT	DEALLOCATE
User operation
DISMOUNT
[UPDATE]
DEALLOCATE

The mount command is required even if the mount mode is NOMOUNT. The current volume set is always described by the symbols listed in Table 11-6.

Table 11-6 DCL symbols used by MEDIA

Symbol	Meaning
MEDIA_EXT	This is the external name of the current medium. In the case of an INCORE medium, this is equal to the word INCORE and MEDIA_EXT_1 contains the user supplied external label. Only this symbol is left intact by a DISMOUNT command, all others are deleted.
All of the following are deleted by the DISMOUNT command.
MEDIA_EXT_1	This is the external name of the current medium. This is usually equal to MEDIA_EXT.
MEDIA_EXT_n	All the volume labels of a set are contained in a series of symbols of this format, where "n" is equal to the number of the volume in the volume set.
MEDIA_INT	The internal label of the master volume is contained in this symbol.
MEDIA_INT_n	All the volume internal labels are contained in this group of symbols. Note that MEDIA_INT_1 is always equal to MEDIA_INT. Where "n" is equal to the number of the volume in the volume set.
INCORE medium header information:
MEDIA_HDR_RECORD_n	This group of symbols (n = 0...9) for any temporary INCORE medium contains the entire header file entry. It is represented in a modify hexadecimal text format. This information is passed on to any Media Jobs that are created.

Three logical names are used during the processing. The logical names are listed in Table 11-7.

Table 11-7 Logical names used by MEDIA

Name	Meaning
MEDIA	This name is equivalent to the physical device that is obtained during execution of the ALLOCATE command.
TAPE	This name is equivalent to the physical device that is mounted during execution of the MOUNT command when mounting a tape type of medium. This is always identical to the logical name MEDIA.
DISK	This name is equivalent to the physical device that is mounted during execution of the MOUNT command when mounting a disk type of medium. This is always identical to the logical name MEDIA.

The reason for having two similar names, TAPE and DISK, which are always equivalent to MEDIA, is that it allows the user who writes a command file, that will only work on a DISK, to explicitly use the name DISK. In this way, the job will fail if this same command file is used with a tape medium since only one of these is defined for any particular job.

11.5.3 User supplied directory contents files

There are two commands for manually supplying the Librarian with a file containing directory contents that has been created by the user. They are:

Command format: MEDIA media_name READ_IN_TEXT file_name MEDIA media_name APPEND_JOURNAL file_name

READ_IN_TEXT will read in a text file and place it in the library. This file will replace any previous directory contents information. The status update flag is set to TDR. Any subsequent directory search operations will search this file.

APPEND_JOURNAL will read and append a BACKUP journal file to any existing journal file in the library. If no existing file is found, then a new one is created. The status update flag is set to BJL. Any subsequent directory search operations will search this file. It is important to note that to erase any contents file, all that is needed is to use the INITIALIZE qualifier or command with any job or device command.

11.5.4 MEDIA_BACKUP command

One useful illustration of the above features is a simple means for using VMS BACKUP to add files to a medium, and insert the resultant journal file into the library. In the following example, we are implementing a command "MEDIA_BACKUP" via a command file which performs the necessary operations of doing a backup and then inserting the journal file into the library.⁹

Typical command:

$ MEDIA 1234 $MEDIA_BACKUP *.* MEDIA:ALL.BCK or $ MEDIA/INITIALIZE 1234 $MEDIA_BACKUP *.* MEDIA:ALL.BCK

Where:

$ MEDIA_BACKUP :== @MDBACKUP.COM

and MDBACKUP.COM contains:

$ SET NOON $ BACKUP/JOURNAL='MEDIA_EXT' 'P1' - MEDIA:'F$PARSE(P2,,,"NAME")'/LABEL='MEDIA_INT'/SAVESET !(1) $ MEDIA 'MEDIA_EXT' APPEND_JOURNAL - 'F$ELEMENT(0,";",MEDIA_EXT)'.BJL !(2) $ DELETE 'F$ELEMENT(0,";",MEDIA_EXT)'.BJL;

The various operations being performed are:

1. The BACKUP command is used to append a new saveset onto the end of the medium. At the same time, a journal file is recorded. The external label of the medium is taken from the DCL symbol MEDIA_EXT and the internal label is taken from the DCL symbol MEDIA_INT. It is important to supply backup with the volume label even if the medium is not being initialized by BACKUP. This volume information is recorded into the created journal file. This routine needs to be expanded if the volume set contains more than one volume.
2. The APPEND_JOURNAL command will append the new journal information to any information that is already in the library. Only one type of directory contents information can be searched and maintained by the Librarian at one time. Thus a medium containing only BACKUP savesets will have a correct library contents file. A medium with both regular files and journal files cannot have both types of directory contents information present (unless you create a command file that does this). Journal files are kept as BJL files in the library and regular tapes are kept as SDR files.

Certain characteristics should be set for medium that use this type of command procedure:

UPDATE = SIZER MOUNT = FOREIGN LABEL = ANSI

It is important that you set these characteristics before you use the media. Alternately you could expand the above command procedure to include the necessary statements to set these characteristics.