This function is used to uppercase an ASCIIZ string.
Calling Sequence
int far pascal FSH_UPPERCASE(szPathName, cbPathBuf, pPathBuf)
char far * szPathName;
unsigned short cbPathBuf;
char far * pPathBuf;
Where
szPathName is a pointer to the ASCIIZ pathname to be uppercased.
cbPathBuf is the length of the pathname buffer.
pPathBuf is a pointer to the buffer to copy the uppercased path
into
Returns
If no error is detected, a zero error code is returned. If an error is
detected, the following error code is returned:
o ERROR_BUFFER_OVERFLOW
uppercased pathname is too long to fit into buffer.
Remarks
This routine processes DBCS characters properly.
The FSD is responsible for verifying the string pointers and checking for
segment boundaries.
szPathName and pPathBuf may point to the same place in memory.
FSH_UPPERCASE should be called for names passed into the FSD in raw data
packets which are not passed to FSH_CANONICALIZE and should be uppercased,
that is, extended attribute names.
Note: OS/2 does not validate input parameters. Therefore, an FSD should call
FSH_PROBEBUF where appropriate.
ΓòÉΓòÉΓòÉ 6.36. FSH_WILDMATCH - Match using OS/2 wildcards ΓòÉΓòÉΓòÉ
Purpose
This function provides the mechanism for using OS/2 wildcard semantics to form
a match between an input string and a pattern, taking into account DBCS
considerations.
Calling Sequence
int far pascal FSH_WILDMATCH(pPat, pStr)
char far * pPat;
char far * pStr;
Where
pPat is the pointer to an ASCIIZ pattern string. Wildcards are
present and are interpreted as described below.
ppStr is the pointer to the test string.
Returns
If no error is detected, a zero error code is returned. If an error is
detected, the following error code is returned:
o ERROR_NO_META_MATCH
the wildcard match failed.
Remarks
Wildcards provide a general mechanism for pattern matching file names. There
are two distinguished characters that are relevant to this matching. The '?'
character matches one character (not bytes) except at a '.' or at the end of a
string, where it matches zero characters. The '*' matches zero or more
characters (not bytes) with no implied boundaries except the end-of-string.
For example, "a*b" matches "ab" and "aCCCCCCCCC" while "a?b" matches "aCb" but
does not match "aCCCCCCCCCb"
See the section on meta characters in this document for additional
information.
The FSD should uppercase the pattern and string before calling FSH_WILDMATCH
to achieve a case-insensitive compare.
Note: OS/2 does not validate input parameters. An FSD, therefore, should call
FSH_PROBEBUF where appropriate.
ΓòÉΓòÉΓòÉ 6.37. FSH_YIELD - Yield processor to higher-priority thread ΓòÉΓòÉΓòÉ
Purpose
This function provides the mechanism for relinquishing the processor to higher
priority threads.
Calling Sequence
void far pascal FSH_YIELD(void)
Returns
There are no error returns.
Remarks
FSDs run under the 2 mS dispatch latency imposed on the OS/2 kernel, meaning
that no more than 2 mS can be spent in an FSD without an explicit block or
yield. FSH_YIELD will test to see if another thread is runable at the current
thread's priority or at a higher priority. If one exists, that thread will be
given a chance to run.
ΓòÉΓòÉΓòÉ 7. Remote IPL / Bootable IFS ΓòÉΓòÉΓòÉ
This chapter describes the OS/2 Version 2.0 boot architecture and extensions to
the installable file system mechanism (IFSM) to enable booting from an
FSD-managed volume, referred to as Bootable IFS (BIFS). If the volume is on a
remote system, it is referred to as Remote IPL (RIPL).
The mini-FSD is similar to the FSD defined in this document. However, it has
additional requirements for to allow reading of the boot drive before the base
device drivers are loaded. These requirements are fully defined in the two
interface sections of this chapter.
To satisfy its I/O requests, the mini-FSD may call the disk device device
driver imbedded in OS2KRNL (BIFS case) or it may provide its own driver (RIPL
case).
Along with the mini-FSD, the IFS SYS Utility is required to initialize an
FSD-managed volume with whatever is required to satisfy the requirements of the
mini-FSD and this document.
The IFS mechanism includes some additional calls which the mini-FSD may need
while it is linked into the IFS chain.
ΓòÉΓòÉΓòÉ 7.1. Operational Description ΓòÉΓòÉΓòÉ
ΓòÉΓòÉΓòÉ 7.1.1. FAT Boot Procedure ΓòÉΓòÉΓòÉ
The following figure represents the major stages of the OS/2 Version 2.0 FAT
boot procedure.
ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ time
POST BOOT OS2BOOT OS2LDR stage1 stage2 stage3
SECTOR (OS2LDR OS2KRNL
loader)
Figure 4-1. OS/2 Version 2.0 FAT boot procedure
Powering-on the machine or pressing CTRL-ALT-DEL causes control to get
transferred to the power-on-self-test (POST) code. This code initializes the
interrupt vectors to get to the BIOS routines. It then scans the I/O adapters
looking for and linking in any code which exists on them. It then executes an
interrupt 19h (INT 19) which causes control to be transferred to the disk or
diskette boot code.
The INT 19h code reads the boot sector from disk or diskette into memory at
7C00H. Along with code, the boot sector contains a structure called the BIOS
Parameter Block(BPB). The BPB contains information which describes how the disk
is formatted. The boot code uses this information to load in the root directory
and the FAT micro-IFS, which is kept inside the OS2BOOT file. After the
micro-IFS is loaded the boot sector transfer control it via a far jump.
OS2BOOT receives pointers to the RAM copies of the root directory and the BPB.
Using the BPB information, OS2BOOT loads in the FAT table from the disk. Then
using the root directory and the FAT table, the OS2LDR file is loaded into
memory from disk. The inclusion of this micro-IFS in the FAT boot process has
removed the requirement that the OS2LDR file be logically contiguous on the FAT
drive.
OS2LDR contains the OS/2 loader. It relocates itself to the top of low memory,
then scans the root directory for OS2KRNL and reads it into memory. After the
required fixups are applied, control is transferred to OS2KRNL, along with a
pointer to the BPB and the drive number.
OS2KRNL contains the OS/2 kernel and initialization code. It switches to
protected mode, relocates parts of itself to high memory, then scans the root
directory for and reads in the base device drivers (stage 1). Once again, the
BIOS interrupt 13h is used to read the disk, but mode switching must be done.
OS2KRNL then switches to protection level 3 and loads some of the required
dynamic link libraries (stage 2) followed by the device drivers and FSDs
specified in CONFIG.SYS (stage 3). This is done with standard DOS calls and,
therefore, goes through the regular file system and device drivers.
ΓòÉΓòÉΓòÉ 7.1.2. BIFS Boot Procedure ΓòÉΓòÉΓòÉ
The following figure represents the major stages of the OS/2 Version 2.0 BIFS
boot procedure.
ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ time
POST BlackBox OS2LDR stage1 stage2 stage3
(Micro OS2KRNL
FSD)
Figure 4-2. OS/2 Version 2.0 BIFS boot procedure
The major difference between this boot procedure and the FAT boot procedure is
that there is no assumption of booting off of disk. OS/2 Version 2.0 does not
define what should happen between when the POST code is run and when the OS2LDR
program gains control.
When OS2LDR receives control, it must be passed information about the current
state of memory and pointers to the Open, Read, Close, and Terminate entry
points of the micro-FSD. Included in the memory map information is the
positions of the micro-FSD, mini-FSD, RIPL data, and the OS2LDR file itself.
Note: This interface is defined in a next section of this chapter.
As with the FAT boot procedure, the OS/2 loader relocates itself to the top of
low memory, and with the help of the micro-FSD, scans the root directory for
the OS2KRNL file. After reading OS2KRNL into memory and applying the required
fixups, control is transferred to the kernel.
When OS2KRNL receives control, it goes through the same initialization as
before (stage 1) with a couple of exceptions. The module loader is called to
load the mini-FSD from its memory image stored by OS2LDR in high memory to its
final location at the top of low memory. Also, the mini-FSD is called to read
the base device drivers (one at a time) through the stage 1 interfaces.
Before any of the dynalinks are loaded, the mini-FSD will be linked into the
IFS chain (it will be the only link in the chain) and asked to initialize
through FS_INIT. The FS_INIT call marks the transition from stage 1 to stage 2.
The dynalinks are then loaded using the stage 2 interfaces, followed by the
device drivers and FSDs.
The mini-FSD is required to support only a small number of the FSD system
interfaces (the FS_xxxx calls). Therefore, the first FSD loaded must be the
replacement for the mini-FSD.
After the replacement FSD has been loaded, it is called at FS_INIT to
initialize itself and take whatever action it needs to effect a smooth
transition from the mini-FSD to the FSD. It then replaces the mini-FSD in the
IFS chain, as well as in any kernel data structures which keep a handle to the
FSD (for example, the SFT, VPB). This replacement marks the transition from
stage 2 to stage 3.
From this point on, the system continues normally.
When called from OS2KRNL after being linked into the IFS chain, the interface
will be as described in previous chapters of this document. Note that the
FS_INIT interface for a mini-FSD has an additional parameter, as compared to
the FS_INIT interface for an FSD.
When called from OS2KRNL, before being linked into the IFS chain, the interface
will be through the MFS_xxxx and MFSH_xxxx entry points. These interfaces are
described in this chapter. Many of these interfaces parallel the interfaces
defined for FSDs, while others are unique to the mini-FSD.
The mini-FSD is built as a dynamic link library. Supplied functions are
exported by making the function names public. Helper functions are imported by
declaring the helper names external:far. It is required only to support reading
files and will be called only in protect mode. The mini-FSD may NOT make
dynamic link system calls at initialization time.
Due to the special state of the system as it boots, the programming model for
the mini-FSD during the state 1 time frame is somewhat different than the model
for stage 2. This difference necessitates 2 different interfaces between OS/2
and the mini-FSD.
During stage 1, all calls to the mini-FSD are to the MFS_xxxx functions. Only
the MFSH_xxxx helper functions are available. These are the interfaces which
are addressed in this document. Many of these interfaces parallel the
interfaces defined for FSDs while others are unique to the mini-FSD.
During stage 2, the mini-FSD is treated as a normal FSD. Calls are made to the
FS_xxxx functions and all FSH_xxxx helper functions are available.
During stage 3, the mini-FSD is given a chance to release resources (through a
call to MFS_TERM) before being terminated.
Transition from stage 1 to stage 2 is marked by calling the FS_INIT function in
the mini-FSD. Transition from stage 2 to stage 3 is marked by calling FS_INIT
in the FSD.
Figure 4-3 on page 4-6 shows the functions called during a typical boot
sequence:
ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ time
stage1 stage2 stage3
MFS_INIT
MFS_OPEN
MFS_READ
MFS_CHGFILEPTR
MFS_CLOSE
FS_INIT
FS_MOUNT/ATTACH
FS_OPEN
FS_READ
FS_CHGFILEPTR
MFS_TERM
Figure 4-3. Typical boot sequence
No files are open at the transition from stage 1 to stage 2. Also, only a
single file at a time is open during stage 1. Files and volumes are open during
the transition from stage 2 to stage 3 (the mini-FSD to the FSD). The FSD must
do whatever is necessary for it to inherit them. The FSD will not receive
mounts/attaches or opens for volumes and files which were mounted/attached and
opened by the mini-FSD. Also, multiple files may be open simultaneously during
stages 2 and 3.
A special set of helper functions are available to the mini-FSD to support an
imbedded device driver. This might be required for situations such as remote
IPL where the boot volume is not readable through DOVOLIO. These special helper
functions (referred to as imbedded device driver helpers) are available during
all stages of the mini-FSD's life. Note that the list of error return codes for
the helper functions is not exhaustive, but rather represents the most common
errors returned.
Because the mini-FSD is a new component added to the boot sequence, a new
interface to OS2LDR is required.
The name and attributes of the mini-FSD must match EXACTLY the name and
attributes of the replacement FSD.
Due to the instability of the system during initialization, any non-zero return
code indicates an error has been encountered. The actual return code may not
bake any sense in the context of the function called (for example, having
ERROR_ACCESS_DENIED returned from a call to MFSH_LOCK when in fact an invalid
selector was passed to the helper). It is also possible for the system to hang
or reboot itself as a result of invalid parameters being passed to a helper
function.
ΓòÉΓòÉΓòÉ 7.2.3. Stage 1 Interfaces ΓòÉΓòÉΓòÉ
The following functions must be made available by the mini-FSD. These functions
will be called only during stage 1.
o MFS_CHGFILEPTR
o MFS_CLOSE
o MFS_INIT
o MFS_OPEN
o MFS_READ
o MFS_TERM
The following helper functions are available to the mini-FSD. These functions
may be called only during stage 1.
o MFSH_DOVOLIO
o MFSH_INTERR
o MFSH_SEGALLOC
o MFSH_SEGFREE
o MFSH_SEGREALLOC
ΓòÉΓòÉΓòÉ 7.2.4. Stage 2 Interfaces ΓòÉΓòÉΓòÉ
The intent of stage 2 is to use the mini-FSD as an FSD. Therefore, all the
guidelines and interfaces specified in this document apply with the following
exceptions.
The following functions must be fully supported by the mini-FSD:
o FS_ATTACH (remote mini-FSD only)
o FS_ATTRIBUTE
o FS_CHGFILEPTR
o FS_CLOSE
o FS_COMMIT
o FS_INIT
o FS_IOCTL
o FS_MOUNT (local mini-FSD only)
o FS_NAME
o FS_OPENCREATE (existing file only)
o FS_PROCESSNAME
o FS_READ
Note that since the mini-FSD is only required to support reading,
FS_OPENCREATE need only support opening an existing file (not the create or
replace options).
None of the other functions required for FSDs are required for the mini-FSD
but must be defined and should return the ERROR_UNSUPPORTED_FUNCTION return
code.
The full complement of helper functions specified in this document is
available to the mini-FSD. However, the mini-FSD may NOT use any other dynamic
link calls.
ΓòÉΓòÉΓòÉ 7.2.5. Stage 3 Interfaces ΓòÉΓòÉΓòÉ
The intent of stage 3 is to throw away the mini-FSD and use only the FSD.
The following functions must be supported by the mini-FSD:
(.txt)