Specification Version: 2.6

Last Modification: 6-April-2011

Introduction

The CEF Media Specification defines classes, their semantics, and corresponding file formats for the Computer Emulation Framework. Note that this specification is build upon the CEF Core Specification. The support for media is provided via media presentation manager components (herein simply Presentation Manager), each of which supports reading and writing a specific format to an external file and displaying the data to the user. These files represent the virtual equivalent of various physical media (such as disks, tapes, punch cards, etc.).

A Presentation manager component serves up a Presentation manager via two API calls:

TPresentation_Manager* Get_Presentation_Server()

Creates and returns a Presentation Manager.

Integer Version()

Returns the version number of the component, times 10. For now, the result should be 10 (V1.0).

TPresentation_Manager class

A TPresentation_Manager object serves up one or more TPresenters. It contains the following methods:

TPresenter* Get_Presenter( string S, Integer Parent, TMedia* Array, TCEF_Media_File_Header* Header )

Creates and returns a TPresenter object for the format name passed in S. If the format name is not known, NULL is returned. Parent is a handle to the parent window in which to display the data. Array is a TMedia object connected to an actual file. Header is the header from the file (NULL if none).

string Get_Name( Integer Index )

Returns a name of a supported media format. Index is 0 for the first name. If Index is out of range, the function returns NULL.

string Get_Path( Integer Index )

Returns the path of a supported media format. Index is 0 for the first format. If Index is out of range, the function returns NULL. This path indicates the type of media from least- to most-specific, separated with backslashes. For instance: "Disk\NTFS", "Disk\Hard\ODS-1" or "Tape\ANSI". This is solely to provide the UI with a means of presenting all the possible options to the user in an organized way.

Integer Version()

Returns the version of the specification that this object conforms to, times 10. For instance, 10 is V1.0.

TPresenter class

A TPresenter object displays a virtual media file to the user. It contains the following methods:

void Redraw()

Causes the displayed data to redraw itself.

void Set_Bounds( Integer Width, Integer Height )

Sets the size of the displayed data, in pixels.

TUEC Terminate()

Tells the object to destruct.

void Get_Header( TCEF_Media_File_Header* Header )

The object returns the current media header in Header.

TMedia class

Media components provide three views of data: 1) raw data from the virtual media file, 2) cooked data that provides a low-level format view of the data (such as viewing tapes as a series of records, or disks as a series of sectors), and 3) a formatted view of the data which provides a high-level format view of the data (such as ANSI format for tapes). The TMedia class is a level 1 component that provides the raw data view and is the class from which other media manager classes descend. Level 2 classes such as TTape_Media provide a low-level format view of the data. Specific tape media manager components (level 3) descend from TTape_Media. Level 2 also implements a position which indicates the current location of the read/write heads in relation to the virtual media. For sequential access media (such as tape), this is the position of the head in relation to the tape. For random access media (such as disk), this is the cylinder (or track) position of the read/write head.

The TMedia class defines the media component interface. It can be viewed as an interface to an array of bytes in the media file. This is a "raw" view of the data. Specific media manager components descend from this class and provide "cooked" views of the data.

By default, virtual media files are considered to be simply a raw data image (in some cases, there may be informational data embedded as well). Media Manager components can access these files by default. However, for non-CEF-standard raw data, a CEF Media header can be prepended to the file that will indicate the format so that CEF can read the file. The format of the CEF Media header is described later.

TUEC Initialize()

Initialize the object. Returns result of initialization attempt.

TUEC Terminate()

Terminate the use of the object. Returns result of termination. This generally should not be used - instead, use the Detach method.

void Attach()

Increments the reference count for the object.

void Detach()

Decrements the reference count for the object. When count reaches 0, the object is destroyed.

integer Interface_Version()

Version of the COM interface for this object. This is the version times 10. So, Version 2.4 would be 24.

integer Facility_ID()

Facility ID for the facility represented by this object. Returns -1 if no facility assigned.

integer Facility_Version()

Facility version. Result only has meaning if Facility_ID doesn't return -1.

TDebug_Interface* Debugger()

Returns a debugging interface for the object. Returns NULL if not supported.

void* Extension()

Returns a pointer to an object with extended common COM methods for object. Always returns NULL for now.

byte Get_Byte( int64 Index )

Return a byte from the given index.

void Set_Byte( int64 Index, byte Value )

Set a byte at a specific index.

boolean Read_Only()

Returns true if the data is read-only.

int64 Low_Bound( Subscript : integer )

Returns low bound of specified subscript. Subscript should always be 0. Should always return 0.

int64 High_Bound( Subscript : integer )

Returns high bound of specified subscript. Subscript should always be 0. This returns the count of bytes in the virtual media file, minus any file header.

integer Subscripts()

Returns number of subscripts. Should always return 1.

TUEC Insert( Index, Count : int64 ; Fill : byte )

Insert Count bytes starting at index Index, filling with Fill.

TUEC Delete( int64 Index, int64 Count )

Delete Count bytes starting at index Index (inclusive), truncating file by Count.

TUEC Get( int64 Index, int64 Count, string Data )

Reads Count bytes from media, starting at index Index, into buffer Data

TUEC Put( int64 Index, int64 Count, string Data )

Writes count bytes from Data to media, starting at index Index.

TTape_Media class

The TTape_Media class provides a tape record view of a virtual media file. Many of the methods allow either record or byte positioning, or both. It is recommended to use one or the other rather than mixing the two. It is also recommended that record positioning be used for most purposes.

By default, a virtual tape file consists of a series of records which are both preceded and followed by a 4-byte integer count, indicating the size of the record between them. A single 4-byte integer size of 0 indicates a "tape mark". An inter-record Gap (IRG) is implied between each record (and its two size values). IRG size has no effect on the size of the physical file, but can affect when the tape is considered to be "full". Likewise the size of the tape marks has no effect on the size of the physical file, but can affect when the tape is considered "full". Physical start of tape marker is implied at byte 0 of the physical data. Physical End of Tape mark is implied at the position indicated by tape length, or else at the maximum size that the file may be. Note that the default corresponds to the SimH virtual tape format.
There are several methods that allow setting and getting various metrics such as the IRG size, how large the size indicators are, and so forth. Changing these on a non-zero-length virtual media file may render the file unreadable.

Note that two, or more, tape marks in a row indicate a logical end of tape.

By default, media files are considered to be simply a raw data image.

Integer Get_BPI()

Retrive tape's BPI setting (0 indicates any).

void Set_BPI( integer Value )

Set tape's BPI setting (0 indicates any).

Integer Get_Length()

Returns length of tape (in feet). 0 = infinite

void Set_Length( Integer Value )

Sets length of tape (in feet). 0 means infinite.

Integer Get_Count_Length()

Returns size of tape record-size records, in bytes.

void Set_Count_Length( Integer Value )

Sets size of tape record-size records, in bytes.

Boolean Get_After()

Returns True if record-size records follow data record.

void Set_After( Boolean Value )

Set to True if record-size records follow data record.

Integer Get_IRG_Length()

Set inter-record gap length, in 1/1000" increments.

void Set_IRG_Length( Integer Value )

Set inter-record gap length, in 1/1000" increments.

Integer Get_TM_Length()

Set tape mark length, in 1/1000" increments.

void Set_TM_Length( Integer Value )

Set tape mark length, in 1/1000" increments.

int64 Record_Count()

Count of records on the tape (includes tape marks).

int64 Record_Length( int64 Index )

Returns length of record Index. If result is 0, then there is a tape mark at the position.

Boolean At_BOT()

True if at BOT.

Boolean At_PEOT()

True if at physical EOT.

Boolean At_LEOT()

True if at logical EOT.

int64 Position( Boolean Records )

Current position on tape. If Records is true, this is the record position, otherwise it is the byte position.

void Seek( int64 Count, Boolean Records, Boolean Relative )

Moves current position on tape. Parameters: Count : Amount/where to move. If Relative is false, this is the absolute data position to move to. If relative is true, this is how many bytes to move from the current position (negative values move backward).
Records: True to interpret Count as record count, False to interpret as byte count.
Relative: True to move relative to current position. False to move to absolute position.

void Seek_BOT()

Move to beginning of tape.

void Seek_LEOT()

Move to logical end of tape.

void Seek_PEOT()

Move to physical end of tape.

Boolean Support_TM()

Returns true if tape marks supported on tape.

void Add_TM()

Add a tape mark to the tape.

int64 Read( string Data, int64 Count )

Read Count bytes into Data. Returns the count actually read. Cannot read beyond current record.

char* Read_Record( int64& Count )

Returns current reoord. Count is ignored on call. On return, it is the size of the read record.

TUEC Write( string Data, int64 Count )

Write Count bytes from Data to tape. Count must be larger than 0. This is a raw operation and does not prefix the data with a count or any other such processing.

TUEC Write_Record( string Data, int64 Count )

Write a record of Count bytes from Data to tape. Count must be larger than 0.

CEF Virtual Media File Header format

The CEF Virtual Media File Header is a fixed 256-byte area at the very beginning of a virtual media file. The first eleven (11) bytes have the same meaning in all virtual media files. The remainder of the header is dependent upon the type of virtual media in question. The fixed part of the header (TCEF_Media_File_Header) is as follows.

Byte(s)	Mnuemonic	Meaning
0-1	Prefix	Both bytes must be 255.
2	ID	Must be 255.
3-6	Facility	Type of file. 123 = CEF Tape media file. 124 = CEF Disk media file.
7-10	Version	File format version. Must be 10 (V1.0)

Tape Media file headers (TCEF_Tape_Media_Header) contain the following additional data:

Byte(s)	Mnuemonic	Meaning
11	Format_Name_Length	The number of valid characters in Format_Name (its length).
12-74	Format_Name	The name of the high-level format used on the tape. eg "DOS-11 tape".
75-78	BPI	Density of tape in linear BPI (0=not specified)
79-82	Length	Length of tape, in feet (0=infinite).
83	Size_Length	Length of size records, in bytes (1-8).
84	After	Non-zero if a size record follows and preceeds data. Zero if size records only preceed data.
85-88	IRG_Length	Length of IRGs, in 1/1000" (eg 750=.75")
89-92	TM_Length	Length of Tape marks, in 1/1000" (eg 10000=10")

Disk Media file headers (TCEF_Disk_Media_Header) contain the following additional data:

Byte(s)	Mnuemonic	Meaning
11-18	Max_Size	Maximum disk size, in cooked data bytes (this, divided by Sector_Size, provides the max number of sectors).
19-22	Sector_Lead_In_Size	Length of formatting data before actual sector data: 0 = none, -1 = variable.
23-26	Sector_Lead_Out_Size	Length of formatting data after actual sector data: 0 = none, -1 = variable. Note that if both sector lead-in and lead-out are variable, the disk can only be read in raw mode.
27-30	Track_Lead_In_Size	Length of formatting data before first sector on track: 0 = none, -1 = variable.
31-34	Track_Lead_Out_Size	Length of formatting data after last sector on track: 0 = none, -1 = variable. Note that if both track lead-in and lead-out are variable, the disk can only be read in raw mode.
35-38	Sector_Size	Length of actual (cooked) data for each sector, in bytes.
39	Heads	Number of heads/surfaces (0 = unknown).
40-43	Tracks	Number of tracks/cylinder per head (0 = unknown).
44-47	Sectors	Number of sectors per track (0 = unknown).
48-55	Errors	Pointer to on-disk error data (0 = none).
56	Default_Data	Data to return for phantom sectors.
57-64	Default_Track_Lead_In	Pointer to default track lead-in data (must be 0 if variable or not used, or if Sectors [per track] is 0).
65-72	Default_Track_Lead_Out	Pointer to default track lead-out data (must be 0 if variable or not used or if Sectors [per track] is 0).
73-80	Default_Sector_Lead_In	Pointer to default sector lead-in data (must be 0 if variable or not used).
81-88	Default_Sector_Lead_Out	Pointer to default sector lead-out data (must be 0 if variable or not used).
89-96	Index	Pointer to data index (0 = pre-allocated, which isn't allowed for disks with variable lead-in/out).
97-100	Flags	Flags: and 1 = pre-allocated, Index points to actual data and 2 = Composite. Data following header is a series of null-terminated filenames, indicating disk data files - in order of sector ranges and 4+ = reserved
101	Mask_Length	Length of following mask (0-63).
102-164	Mask	Bitmask for addressing: [1] is bit 1, [2] is bit 2, etc. Each element is one of the following: (space) = Unused H = head/surface C = cylinder/track S = sector For instance, "HHCCCSSSSSSSS" indicates that the lowest 2 bits specify the head (0-3), bits 3-5 indicate cylinder (0-7), and bits 6-13 indicate sector (0-255). If all elements are spaces, the disk cannot be accessed via Head/Cylinder
165-172	Flaws	Pointer to flaw data (0 = none).
173-176	SN_Size	Size of serial number data, in bytes (0 = none).
177-184	Serial_Number	Pointer to pack serial-number data (must be 0 if SN_Size is 0).