Return to read.me CVS log

Up to [OS/2 SDKs] / os232sdk / toolkt20

Annotation of os232sdk/toolkt20/read.me, revision 1.1

1.1     ! root        1: As the SDK represents Beta-level code, there will be bugs
        !             2: that we discover as we further test the code prior to
        !             3: shipping each release.  Below are the items we have found to
        !             4: date.  Also listed is advice on developing applications with
        !             5: this release of the SDK.
        !             6: 
        !             7: SYSTEM CONFIGURATION NOTES:
        !             8: 
        !             9:      a.  If your system has a secondary partition formatted
        !            10:      with HPFS before you install, the System Install does
        !            11:      not automatically add the proper support to your disk.
        !            12:      You will need to add following line to your CONFIG.SYS
        !            13:      (for an HPFS partition "D:"):
        !            14: 
        !            15:           IFS=C:\OS2\HPFS.IFS /C:64 /AUTOCHECK:D
        !            16: 
        !            17:      b.  You may notice that the DIR command is slow in this
        !            18:      pre-release of the system.  A temporary workaround is
        !            19:      to add the following two lines to your CONFIG.SYS:
        !            20: 
        !            21:           CODEPAGE=437,850
        !            22:           DEVINFO=KBD,US,C:\OS2\KEYBOARD.DCP
        !            23: 
        !            24:      c.  The install process does not automatically
        !            25:      configure your system to support XMS extended memory in
        !            26:      the DOS boxes.  To add this support, insert this line
        !            27:      into your CONFIG.SYS:
        !            28: 
        !            29:           DEVICE=C:\OS2\MDOS\VXMS.SYS
        !            30: 
        !            31:      This line must come after the line
        !            32: 
        !            33:            DEVICE=C:\OS2\MDOS\VEMM.SYS
        !            34: 
        !            35: 
        !            36: NETWORK SUPPORT NOTES:
        !            37: 
        !            38:      a.  Certain systems configurations and network cards
        !            39:      will not work with the SDK.  Configurations that are
        !            40:      known to work are:
        !            41: 
        !            42:      PS/2 Model 80, 3Com EtherlinkMC card, NetBEUI transport
        !            43:      Compaq 386/20, 3Com EtherlinkII card, NetBEUI transport
        !            44:      Compaq 386/16, Ungermann-Bass 16-bit card, XNS
        !            45:           monolithic  transport
        !            46:      Compaq 386/20, Ungermann-Bass 8-bit net card, XNS
        !            47:      PS/2 Model 80, Ungermann-Bass NUI card, XNS
        !            48:      Northgate 33Mhz, Ungermann-Bass 16-bit net card, XNS
        !            49:      PS/2 Model 80, IBM Token Ring Adapter A, NetBEUI
        !            50: 
        !            51:      Configurations that are known to not work are:
        !            52: 
        !            53:      PS/2 Model 80, Ungermann-Bass NICps/2 card, XNS
        !            54:            monolithic transport
        !            55:      Compaq 386/20e, 3Com Etherlink II card, XNS NDIS
        !            56:            transport
        !            57: 
        !            58:      For this pre-release, we have not tested a large number
        !            59:      of combinations of network cards and server software.
        !            60:      If you run into a configuration that you think should
        !            61:      be supported but fails, please report the problem via
        !            62:      Microsoft Online.
        !            63: 
        !            64:      b.  The workstation software in this pre-release of the
        !            65:      SDK will not communicate with IBM Lan Servers over an
        !            66:      IBM Baseband or Broadband network.
        !            67: 
        !            68:      c.  On machines using the FAT file system, the network
        !            69:      support install may set the DISKCACHE at too high a
        !            70:      level for your machine, leaving you with too little
        !            71:      memory for the OS/2 system.  One symptom is that the
        !            72:      NET START WORKSTATION command will fail with an "Access
        !            73:      Denied" error.  If you suspect you may be experiencing
        !            74:      this error, change the line in CONFIG.SYS to
        !            75: 
        !            76:           DISKCACHE = 128
        !            77: 
        !            78:      and try rebooting your system.
        !            79: 
        !            80: 
        !            81: 
        !            82: API NOTES:
        !            83: 
        !            84:      a.  When IMPORTing a system API into your source code,
        !            85:      you should do so using only the ORDINAL for the
        !            86:      function, not the name.  Ordianals for each API are
        !            87:      given in the file BSEORD.H  This rule will be fully
        !            88:      enforced in a future release of the SDK.
        !            89: 
        !            90:      b.  The 32-bit MLE (Multi-Line Edit) APIs are not fully
        !            91:      implemented in this release of the SDK.
        !            92: 
        !            93:      c.  The 32-bit version of the WinAddSwitchEntry API is
        !            94:      not working in this release of the SDK.
        !            95: 
        !            96:      d.  The constants used for the INCL_DOSDEVICES class of
        !            97:      API in bsedos.h and bsedos16.h have been changed since
        !            98:      the first SDK, as promised in the earlier readme file.
        !            99:      The definitions are now equivalent to those used in the
        !           100:      OS/2 1.2 Toolkit.
        !           101: 
        !           102:      e.  If an application is to remain 16-bit, it should be
        !           103:      compiled and linked with the 1.2 toolkit header files
        !           104:      and libraries.  If it is compiled with a 16-bit
        !           105:      compiler (c5.1/c5.2/c6.0) and OS/2 2.0 SDK
        !           106:      header files, and linked with the 2.0 SDK's libraries,
        !           107:      it is probable that the application will have
        !           108:      references to API's that are not in the same system DLL
        !           109:      in the 2.0 system that they were in the 1.2 system.
        !           110:      This will cause the 1.2 system to refuse to load the
        !           111:      application because it is unable to resolve the dynamic
        !           112:      links.  
        !           113: 
        !           114:      f.  The DosQuerySysInfo API is not fully implemented.
        !           115:      You cannot get information on shared and private memory
        !           116:      available to the calling process.
        !           117: 
        !           118:      g.  DosStartSession:  if the SessionType field of the
        !           119:      STARTDATA structure is 0 for "allow the system to
        !           120:      decide", a PM application will not be started
        !           121:      correctly.  If it is a 3, specifying a PM app
        !           122:      explicitly, the application will start correctly.
        !           123: 
        !           124: 
        !           125: 
        !           126: QUICKHELP NOTES:
        !           127: 
        !           128:      a.  To reduce the number of open file handles in
        !           129:      QuickHelp, you can concatenate the files adg20.hlp,
        !           130:      api1.hlp, and api2.hlp into a single database called
        !           131:      msos20.hlp.  To do so type
        !           132: 
        !           133:           COPY /B API1.HLP+API2.HLP+ADG20.HLP  MSOS20.HLP
        !           134: 
        !           135:      b.  We have noticed some errors in accessing option
        !           136:      information in the MASM386.HLP database under
        !           137:      QuickHelp.  If the topic you are seeking is positioned
        !           138:      at the top of the screen when you click on it with the
        !           139:      mouse, the reference won't take you to the right spot
        !           140:      in the database.  The workaround is to simply position
        !           141:      the topic further down on the screen before you click
        !           142:      on it.
        !           143: 
        !           144: 
        !           145: 
        !           146: CV386 NOTES:
        !           147: 
        !           148:      a.  Debugging floating point programs on a 386 system
        !           149:      without a 387 The system emulator currently does not
        !           150:      single-step correctly.  This means that users who are
        !           151:      single stepping at assembly level will see more than
        !           152:      one instruction executed when they single-step under
        !           153:      CV386. More precisely, if the cursor is on a floating
        !           154:      point instruction, hitting F8 or F10 to single-step
        !           155:      will result in the execution of the current instruction
        !           156:      and following until a non floating point instruction is
        !           157:      executed and  
        !           158: 
        !           159:                Cursor->       FADD... 
        !           160:                               FSTP... 
        !           161:                               MOV       AX,.... 
        !           162:                               MOV       DX,....  
        !           163: 
        !           164:           If you single step at this point on a system
        !           165:      without a 387, you will end up on the "mov dx"
        !           166:      instruction.  (FADD and FSTP are both floating point
        !           167:      instructions.)   
        !           168: 
        !           169:      b.  If you are single-stepping in assembler mode and
        !           170:      execute an instruction which cases a fatal protection
        !           171:      fault (gp fault or page fault), the CS:EIP will be off
        !           172:      in the exception dispatcher, not in user code.  If the
        !           173:      user knows that this has happened, the user can just do
        !           174:      a "GO" and CV386 will display a message that
        !           175:      a protection fault has occurred and place CS:EIP at the
        !           176:      right place.  If the user is single stepping at source
        !           177:      level mode, there is no problem.  Another solution
        !           178:      besides doing a "GO" is to "View" your previous source
        !           179:      code and do a GO UNTIL on the next instruction.  This
        !           180:      will get you a proper reporting of the GP fault.
        !           181: 
        !           182:      Source level single stepping works better:  it reports
        !           183:      a GP fault and leave the CS:IP pointing at the
        !           184:      offending instruction.
        !           185: 
        !           186:      c.   If you are debugging an .EXE which is loaded from
        !           187:      a floppy, any breakpoints you set will apply to all
        !           188:      instances of that program on the system, not just the
        !           189:      instance running under CV386.  You may copy the .EXE to
        !           190:      your hard disk to avoid this.
        !           191: 
        !           192:      d.  The Restart command on the Run menu (equivalent to
        !           193:      the "l" command) can cause the system to crash.
        !           194: 
        !           195: 
        !           196: 
        !           197: UTILITIES NOTES:
        !           198: 
        !           199:      a.  MEP will not execute background compiles.  We
        !           200:      recommend opening a second window and using the command
        !           201:      line to execute a compile.  Under certain conditions
        !           202:      (such as attempting to execute a background compile)
        !           203:      MEP will hang when it runs out of stack space.  To free
        !           204:      up stack space, delete or edit out file name entries in
        !           205:      the MEP.TMP file.
        !           206: 
        !           207:      b.  LIB and LINK386 currently do not accept long file
        !           208:      names for library files.
        !           209: 
        !           210:      c.  When LINK386 encounters fixups for a page of code
        !           211:      or data that is otherwise unitialized, it writes
        !           212:      incorrect fixup information to the executable, which
        !           213:      causes fixups for the page to be ignored by the loader.
        !           214:      This will only occur in some instances of linking 16-
        !           215:      bit object modules in 32-bit EXEs (mixed model
        !           216:      programming).
        !           217: 
        !           218:      If you are using mixed model and suspect this problem,
        !           219:      verify by running "exehdr -v <exefile>". If the file
        !           220:      contains ZEROED pages with fixups (i.e. if a non-zero
        !           221:      physical page number is associated with a ZEROED page),
        !           222:      you will see:
        !           223: 
        !           224:       no. virtual  virtual  page     file     flags
        !           225:           address   size    map      pages
        !           226: ...
        !           227:      0005 00050000 00000002 00000007 00000001 READABLE,
        !           228:                                               WRITEABLE,
        !           229:                                               NONSHARED,
        !           230:                                               LOADONCALL,
        !           231:                                               NONRESOURCE,
        !           232:                                               DISCARDABLE,
        !           233:                                               VALID-PAGES,
        !           234:                                               SWAPPABLE,
        !           235:                                               16:16 ALIAS,
        !           236:                                               16-bit, NOIOPL
        !           237: 
        !           238:                                    logical  physical flags
        !           239:                                    page      page
        !           240:                                    00000001 00000008 ZEROED
        !           241: 
        !           242:      and if the following message appears while dumping
        !           243:      fixup records, 
        !           244: 
        !           245:           EXEHDR: fatal U1140: out of memory
        !           246: 
        !           247:      then this problem is likely the cause of the failure.
        !           248: 
        !           249:      Workaround:  Add an assembler module to append some
        !           250:      initialized data to the group that defines the ZEROED
        !           251:      page (object number 5 in the above example).  Look in
        !           252:      the map file to determine the name and class name of
        !           253:      the last segment in the group.  Use the below asm file,
        !           254:      replacing <segname> and <classname> with the names from
        !           255:      the map file, and make sure the alignment (dword) and
        !           256:      other attributes (public, use32) are the same as the
        !           257:      map file segment.  Link the resulting .obj file with
        !           258:      the rest of the objects, by putting the new .obj file
        !           259:      at the END of the .obj file list.
        !           260: 
        !           261:           .386
        !           262:           <segname> segment dword public use32 '<classname>'
        !           263:           dw  1234h
        !           264:           <segname> ends
        !           265:           end
        !           266: 
        !           267: 
        !           268:      d.  MKMSGF:   This tool has the following known
        !           269:      problems:
        !           270: 
        !           271:           i. No message text file checking.  MKMSGF used to
        !           272:           check for header id, message numbers, out of
        !           273:           sequence msg IDs, missing messages, and repeated
        !           274:           messages.  With this version, very little if any
        !           275:           checking is done.  The user is warned that syntax
        !           276:           errors in the input text file most likely will not
        !           277:           be found.
        !           278: 
        !           279:           ii. There is a maximum of about 5000 messages
        !           280:           allowed.
        !           281: 
        !           282:           iii. No checking for naming the same file name for
        !           283:           both input and output file.  Using the same name
        !           284:           will put the output on top of the input file.
        !           285: 
        !           286:           iv. The new switches /C,/A, and /I are not
        !           287:           supported.
        !           288: 
        !           289:           v.  The codepage support is not fully active, even
        !           290:           though it is listed for MKMSGF /?.
        !           291: 
        !           292:      e.  H2INC:  This tool has several known limitations
        !           293:      which keep it from being a good general-purpose tool
        !           294:      for converting C headers to MASM include files.  Its
        !           295:      purpose in this SDK is to convert the system headers in
        !           296:      the OS2H directory into system include files.  To do
        !           297:      so, simply run the MAKEINC command file found in the
        !           298:      MASM\OS2INC directory of the Toolkit.
        !           299: 
        !           300: 
        !           301: 
        !           302: SYSTEM USER NOTES:
        !           303: 
        !           304:      a   There is no BOOT command in OS/2 2.0.
        !           305: 
        !           306:      b.  If you want to create a new DOS session in the Task
        !           307:      Manger list, you must code the PATH to be
        !           308:      
        !           309:           C:\OS2\MDOS\COMMAND.COM
        !           310: 
        !           311:      This will allow you to select "DOS Window" or "DOS Full
        !           312:      Screen" for the Program Type.
        !           313: 
        !           314:      c.  The OS/2 System Editor ("E") has some known
        !           315:      problems in working with this release of the System:
        !           316: 
        !           317:           i.  If you use the Help buttons on the Find, Set
        !           318:           font, or Set colors dialog boxes the editory will
        !           319:           GP fault.
        !           320: 
        !           321:           ii.  The editor will not correctly handle wild
        !           322:           card file names when invoked from the command
        !           323:           line.
        !           324: 
        !           325:           iii.  The editor occasionally locks up when
        !           326:           accessing files on an HPFS file system.
        !           327: 
        !           328:      d.  If you RECOVER from diskette a file that has
        !           329:      diskette read errors in it, the file will be recovered
        !           330:      with the errors.  Normally the recover operation should
        !           331:      fail and an error message written to the screen.
        !           332: 
        !           333:      e.  The SPEEDKEY device driver does not function
        !           334:      reliably on this release.
        !           335: 
        !           336:      f.  When running the system with a BGA (8514A) video
        !           337:      driver, the MVDM sessions do not support DOS
        !           338:      applications running in BGA mode.  They will run lower-
        !           339:      resolution DOS applications.
        !           340: 
        !           341:      g.  Running programs in several DOS sessions
        !           342:      simultaneously can cause hangs in individual DOS
        !           343:      sessions.  Printing and using the math coprocessor from
        !           344:      the DOS sessions appear to be affected by this bug.
        !           345: 
        !           346: 
        !           347: 
        !           348: APPLICATION COMPATIBILITY
        !           349: 
        !           350:      The OS/2 2.0 system is intended to run all OS/2 1.2
        !           351:      applications unmodified.  It is also intended to run
        !           352:      all DOS applications with the exception of those which
        !           353:      use block device drivers (such as network drivers),
        !           354:      those which directly manipulate disk hardware, and
        !           355:      those which use DOS extenders other than EMM and XMS.
        !           356:      If you discover an application which should run under
        !           357:      OS/2 2.0 but doesn't, please report this to Microsoft
        !           358:      Product Support Services so we can correct the problem
        !           359:      in a future SDK.
        !           360: 
        !           361: 
        !           362: 
        !           363: DOCUMENTATION NOTES
        !           364: 
        !           365:      a.  Writing Mixed Model Programs:  This document
        !           366:      contains an error on p. 8, where it states, "you can
        !           367:      use link386 to re-link a 16-bit DLL or application
        !           368:      without any changes."  If the 16-bit code was compiled
        !           369:      with the -Gw switch, then it must be recompiled using
        !           370:      the _loadds keyword where appropriate (or use -Au
        !           371:      instead).
        !           372: 
        !           373:      Also in this document, the _far16 code examples should
        !           374:      have #define INCL_16 in the sources.  This pulls the
        !           375:      right API prototypes from the OS/2 header files.
        !           376: 
        !           377:      In writing mixed-mode C programs, it is important to
        !           378:      initialize a pointer dynamically rather than
        !           379:      initializing it when defined:
        !           380: 
        !           381:           PCH   p = "Hello World"  /*PCH is a pointer type*/
        !           382: 
        !           383:      will cause a fault in a statement like
        !           384: 
        !           385:                i = strlen(p);
        !           386: 
        !           387:      whereas the following code will work:
        !           388: 
        !           389:           PCH p;
        !           390:           ...
        !           391:                p = "hello world"
        !           392:                i = strlen(p);
        !           393: 
        !           394:      b.  Language Release Notes: The section on the use of
        !           395:      FLAT model in MASM386 should be ammended to say "You
        !           396:      should not make direct use of the FS and GS registers,
        !           397:      as these are reserved for use by the OS/2 2.0 exception
        !           398:      handler.
        !           399: 
        !           400:      c.  Programming Reference:  The DosQueryProcType API is
        !           401:      missing from the printed documentation and the QH
        !           402:      database;  it is available in the IPF database.
        !           403: 
        !           404:      To print from the IPF database, you must individially
        !           405:      mark the sections you wish to print.
        !           406: 
        !           407:      d.  Link386 Online help:  This incorrectly states a
        !           408:      maximum stacksize of 64K.  Larger stacksizes can be
        !           409:      specified on the LINK386 command line or in the .DEF
        !           410:      file;  however, there will be some performance
        !           411:      degradation with stacksizes close to or greater than
        !           412:      64K.
        !           413: 
        !           414:      e.  The information provided in this Software
        !           415:      Developer's Kit is preliminary and may contain
        !           416:      inaccuracies or omissions.  This information is subject
        !           417:      to change in both format and content.
        !           418: 

This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.