home *** CD-ROM | disk | FTP | other *** search
/ Microsoft Programmer's Library 1.3 / Microsoft_Programmers_Library.7z / MPL / os2 / prgmr4.txt < prev   
Encoding:
Text File  |  2013-11-08  |  1.1 MB  |  33,884 lines

Text Truncated. Only the first 1MB is shown below. Download the file for the complete contents.
  1.  Microsoft Operating System/2 - Programmer's Reference - Volume 4
  2.  
  3.  
  4.  
  5.  
  6.  
  7.  
  8.  
  9.  
  10.  ────────────────────────────────────────────────────────────────────────────
  11.      Microsoft(R) Operating System/2 - Programmer's Reference - Volume 4
  12.  
  13.  
  14.  
  15.                                   Version 1.2
  16.  ────────────────────────────────────────────────────────────────────────────
  17.  
  18.  
  19.  Microsoft Corporation
  20.  
  21.  
  22.  Information in this document is subject to change without notice and does
  23.  not represent a commitment on the part of Microsoft Corporation. The
  24.  software and/or databases described in this document are furnished under a
  25.  license agreement or nondisclosure agreement. The software and/or databases
  26.  may be used or copied only in accordance with the terms of the
  27.  agreement. The purchaser may make one copy of the software for backup
  28.  purposes. No part of this manual and/or database may be reproduced or
  29.  transmitted in any form or by any means, electronic or mechanical,
  30.  including photocopying, recording, or information storage and retrieval
  31.  systems, for any purpose other than the purchaser's personal use, without
  32.  the written permission of Microsoft Corporation.
  33.  
  34.  
  35.  PUBLISHED BY Microsoft Press
  36.  A Division of Microsoft Corporation
  37.  One Microsoft Way, Redmond, Washington  98052-6399
  38.  
  39.  
  40.  (C) Copyright Microsoft Corporation, 1990. All rights reserved.
  41.  
  42.  
  43.  Printed and bound in the United States of America.
  44.  1  2  3  4  5  6  7  8  9  FGFG  4  3  2  1  0
  45.  Distributed to the book trade in Canada by General Publishing Company, Ltd.
  46.  
  47.  Distributed to the book trade outside the United States and Canada
  48.  by Penguin Books Ltd.
  49.  
  50.  Penguin Books Ltd., Harmondsworth, Middlesex, England
  51.  
  52.  Penguin Books Australia Ltd., Ringwood, Victoria, Australia
  53.  
  54.  Penguin Books N.Z. Ltd., 182-190 Wairau Road, Auckland 10, New Zealand
  55.  
  56.  
  57.  Patent #4,825,358
  58.  
  59.  Patent #4,779,187
  60.  
  61.  
  62.  Microsoft(R), MS(R), and MS-DOS(R) are registered trademarks and
  63.  Press(tm) is a trademark of Microsoft Corporation.
  64.  
  65.  Epson(R) is a registered trademark of Epson America, Inc.
  66.  
  67.  IBM(R), PC/AT(R), Personal System/2(R), and PS/2(R) are registered
  68.  trademarks of International Business Machines Corporation.
  69.  
  70.  Lotus(R) and 1-2-3(R) are registered trademarks of Lotus Development
  71.  Corporation.
  72.  
  73.  PostScript(R) is a registered trademark of Adobe Systems, Inc.
  74.  
  75.  
  76.  LN0702E-120-R00-1189
  77.  
  78.  
  79.  
  80.  Table of Contents
  81.  ────────────────────────────────────────────────────────────────────────────
  82.  
  83.  
  84.  
  85.  Chapter 1  Introduction
  86.  
  87.       1.1   Overview
  88.       1.2   How to Use This Manual
  89.       1.3   Naming Conventions
  90.       1.4   Notational Conventions
  91.  
  92.  Chapter 2  Overviews
  93.  
  94.       2.1   Introduction
  95.       2.2   Installable File Systems
  96.       2.3   Extended Attributes
  97.       2.4   Profile Manager
  98.       2.5   Help Manager
  99.       2.6   Combination Boxes
  100.       2.7   Multiple-Line Entry Fields
  101.       2.8   Printing
  102.  
  103.  Chapter 3  Functions and Messages Directory
  104.  
  105.       3.1   Introduction
  106.       3.2   Directory
  107.       3.3   Functions and Messages
  108.  
  109.  Chapter 4  Types, Macros, Structures
  110.  
  111.       4.1   Introduction
  112.       4.2   Types
  113.       4.3   Macros
  114.       4.4   Structures
  115.  
  116.  
  117.  
  118.  Chapter 1  Introduction
  119.  ────────────────────────────────────────────────────────────────────────────
  120.  
  121.  
  122.  
  123.  
  124.  1.1  Overview
  125.  
  126.  This manual describes the system functions of Microsoft(R) Operating
  127.  System/2 (MS(R) OS/2) that are new or modified for versions 1.2 and later.
  128.  These functions let MS OS/2 programs use the operating system to carry out
  129.  tasks such as reading and writing extended attributes for disk files,
  130.  creating and using multiple-line entry fields, creating and accessing disk
  131.  files through installable file systems, and displaying help text in a
  132.  Presentation Manager application.
  133.  
  134.  MS OS/2 system functions are designed to be used in C, Pascal, and other
  135.  high-level-language programs, as well as in assembly-language programs. MS
  136.  OS/2 programs request operating-system services by calling system functions.
  137.  
  138.  
  139.  This chapter, "Introduction," shows how to use this manual, provides a brief
  140.  description of MS OS/2 calling conventions, illustrates function calls in
  141.  various languages, and outlines MS OS/2 naming conventions.
  142.  
  143.  Chapter 2, "Overviews," describes the new MS OS/2 features and system
  144.  functions. This chapter explains the purpose of the functions and presents
  145.  the operating-system concepts behind them. It also shows how the MS OS/2
  146.  system functions work together to carry out specific tasks.
  147.  
  148.  Chapter 3, "Functions and Messages Directory," lists and describes three
  149.  categories of MS OS/2 functions and messages: those that are new; those that
  150.  are updated or changed; and those that contain corrections for errors that
  151.  appeared in the Microsoft Operating System/2 Programmer's Reference, Volume
  152.  2 and Volume 3. The chapter defines the purpose of each function and each
  153.  message, gives its syntax, describes any parameters, and gives possible
  154.  return values. Many of the descriptions also show program examples that
  155.  illustrate how the function or message is used to carry out simple tasks.
  156.  
  157.  Chapter 4, "Types, Macros, Structures," lists and describes the new and
  158.  updated data types and structures used by the MS OS/2 system functions.
  159.  
  160.  This manual is intended only to describe the MS OS/2 system functions,
  161.  messages, types, and structures that are new or have been modified. It does
  162.  not explain how to use these functions to carry out specific tasks. For more
  163.  information on this topic, see the Microsoft Operating System/2 Programmer's
  164.  Reference, Volume 1.
  165.  
  166.  Also, this manual does not fully describe all MS OS/2 base system and
  167.  Presentation Manager functions. MS OS/2 base system functions enable
  168.  programs to use the operating system to carry out such tasks as reading from
  169.  and writing to disk files; allocating memory; starting other programs; and
  170.  using the keyboard, mouse, and video screen. Presentation Manager functions
  171.  let programs use the multitasking, window-management, and graphics features
  172.  of MS OS/2. For more information on MS OS/2 Presentation Manager functions,
  173.  see the Microsoft Operating System/2 Programmer's Reference, Volume 2. For
  174.  more information on MS OS/2 base system functions, see the Microsoft
  175.  Operating System/2 Programmer's Reference, Volume 3.
  176.  
  177.  In addition, this manual references but does not discuss QuickHelp, the
  178.  display program for Microsoft documentation databases. For more information
  179.  on QuickHelp, see Microsoft Operating System/2 Getting Started, available
  180.  with the Microsoft OS/2 Presentation Manager Toolkit.
  181.  
  182.  
  183.  1.2  How to Use This Manual
  184.  
  185.  This manual provides detailed information about the new and updated MS OS/2
  186.  system functions, messages, and structures. Each item has the format shown
  187.  in Figure 1.1.
  188.  
  189.  (This figure may be found in the printed book).
  190.  
  191.  
  192.  
  193.  
  194.  
  195.  
  196.  
  197.  
  198.  
  199.  
  200.  
  201.  
  202.  
  203.  These are the elements shown in Figure 1.1:
  204.  
  205.    1.  The name of the item and its status (new, change, or correction). The
  206.        name of the function, message, or structure appears on the left. Its
  207.        status is given on the right.
  208.  
  209.    2.  The function, message, or structure syntax. The syntax specifies the
  210.        number of parameters or fields and gives the type of each. It also
  211.        gives the order (from left to right) in which parameters must be
  212.        pushed on the stack. Comments to the right briefly describe the
  213.        purpose of the parameter.
  214.  
  215.    3.  A description of the function, message, or structure, including its
  216.        purpose and details of operation.
  217.  
  218.    4.  A full description of each parameter or field, including permitted
  219.        values and related structures.
  220.  
  221.    5.  A description of the return value, including possible error values.
  222.  
  223.    6.  General comments about how the function, message, or structure can be
  224.        used.
  225.  
  226.    7.  Restrictions that affect how the function operates in real mode.
  227.  
  228.    8.  An example showing how the function or message can be used to
  229.        accomplish a simple task.
  230.  
  231.    9.  A list of related functions and messages.
  232.  
  233.    10. A summary of any changes or corrections.
  234.  
  235.  
  236.  
  237.  
  238.  1.2.1  C Format
  239.  
  240.  In this manual, the syntax for MS OS/2 functions is given in C-language
  241.  format. In your C-language sources, the function name must be spelled
  242.  exactly as given in the syntax, and the parameters must be used in the order
  243.  given in the syntax. This syntax also applies to Pascal program sources.
  244.  
  245.  The following code fragment shows how to call the DosBeep function in a
  246.  C-language program:
  247.  
  248.  /* Play a note for 1 second. */
  249.  
  250.  DosBeep(660,             /* 660 cycles-per-second      */
  251.          1000);           /* play for 1000 milliseconds */
  252.  
  253.  
  254.  
  255.  
  256.  
  257.  1.2.2  MS OS/2 Include Files
  258.  
  259.  This manual uses many types, structures, and constants that are not part of
  260.  standard C language. These items, designed for MS OS/2, are defined in the
  261.  MS OS/2 C-language include files provided with the Microsoft OS/2
  262.  Presentation Manager Softset and the Microsoft OS/2 Presentation Manager
  263.  Toolkit.
  264.  
  265.  In C-language programs, the #include directive specifying os2.h, the MS OS/2
  266.  C-language include file, can be placed at the beginning of the source file
  267.  to include the definitions for the special types, structures, and constants.
  268.  Although there are many MS OS/2 include files, the os2.h file contains the
  269.  additional #include directives needed to process the basic MS OS/2
  270.  definitions.
  271.  
  272.  To speed up processing of the MS OS/2 C-language include files, many
  273.  definitions are processed only if the C-language program explicitly defines
  274.  a corresponding include constant. An include constant is simply a constant
  275.  name, with the prefix INCL_, that controls a portion of the include files.
  276.  If a constant is defined using the #define directive, the corresponding MS
  277.  OS/2 definitions are processed. For a list of the include constants and a
  278.  description of the MS OS/2 system functions they enable, see the Microsoft
  279.  Operating System/2 Programmer's Reference, Volume 1.
  280.  
  281.  
  282.  1.2.3  MS OS/2 Calling Conventions
  283.  
  284.  You must know MS OS/2 calling conventions to use MS OS/2 functions in other
  285.  high-level languages or in assembly language. MS OS/2 functions use the
  286.  Pascal (sometimes called the PLM) calling convention for passing parameters,
  287.  and they apply some additional rules to support dynamic-link libraries. The
  288.  following rules apply:
  289.  
  290.    ■   You must push the parameters on the stack. In this manual, each
  291.        function description lists the parameters in the order in which they
  292.        must be pushed. The left parameter must be pushed first, the right
  293.        parameter last. If a parameter specifies an address, the address must
  294.        be a far address; that is, it must have the form selector:offset. The
  295.        selector must be pushed first, then the offset.
  296.  
  297.    ■   The function automatically removes the parameters from the stack as it
  298.        returns. This means the function must have a fixed number of
  299.        parameters.
  300.  
  301.    ■   You must use an intersegment call instruction to call the function.
  302.        This is required for all dynamic-link-library functions.
  303.  
  304.    ■   The function returns a value, possibly an error value, in either the
  305.        ax register or the dx:ax register pair. Only the di and si register
  306.        values are guaranteed to be preserved by the function. MS OS/2 system
  307.        functions may preserve other registers as well, but they do not
  308.        preserve the flags register. The contents of the flags register are
  309.        undefined; specifically, the direction flag in the register may be
  310.        changed. However, if the direction flag was zero before the function
  311.        was called, it will be zero after the function returns.
  312.  
  313.  
  314.  
  315.  
  316.  The following example shows how MS OS/2 calling conventions apply to the
  317.  DosOpen function in an assembly-language program:
  318.  
  319.  EXTRN DOSOPEN:FAR
  320.  name            db      "abc", 0
  321.  hFile           dw      0
  322.  usAction        dw      0
  323.  
  324.  push    ds                  ; filename to open
  325.  push    offset name
  326.  push    ds                  ; address of file handle
  327.  push    offset hFile
  328.  push    ds                  ; address to store action taken
  329.  push    offset usAction
  330.  push    0                   ; size of new file 0100H
  331.  push    100
  332.  push    0                   ; file's attribute
  333.  push    0010H               ; create file if it does not exist
  334.  push    0041H               ; open file for writing, share with all
  335.  push    0                   ; reserved
  336.  push    0
  337.  call    DOSOPEN
  338.  
  339.  
  340.  
  341.  
  342.  The following example shows how to call the same DosOpen function in a
  343.  C-language program. In C, the DosOpen function name, parameter types, and
  344.  constant names are defined in os2.h, the MS OS/2 C-language include file.
  345.  
  346.  #include <os2.h>
  347.  
  348.  HFILE hfile;
  349.  USHORT usAction;
  350.  
  351.  DosOpen("abc",                /* filename to open                 */
  352.      &hfile,                   /* address of file handle           */
  353.      &usAction,                /* address to store action taken    */
  354.      100L,                     /* size of new file                 */
  355.      FILE_NORMAL,              /* file's attribute                 */
  356.      FILE_CREATE,              /* create file if it does not exist */
  357.      OPEN_SHARE_DENYNONE |     /* share with all                   */
  358.      OPEN_ACCESS_WRITEONLY,    /* open for writing                 */
  359.      0L);                      /* reserved                         */
  360.  
  361.  
  362.  
  363.  
  364.  
  365.  1.2.4  Bit Masks in Function Parameters
  366.  
  367.  Many MS OS/2 system functions accept or return bit masks as part of their
  368.  operation. A bit mask is a collection of two or more bit fields within a
  369.  single byte, or a short or long value. Bit masks provide a way to pack many
  370.  Boolean flags (flags whose values represent on/off or true/false values)
  371.  into a single parameter or structure field. In assembly-language
  372.  programming, it is easy to individually set, clear, or test the bits in a
  373.  bit mask by using instructions that modify or examine bits within a byte or
  374.  a word. In C-language programming, however, the programmer does not have
  375.  direct access to these instructions, so the bitwise AND and OR operators
  376.  typically are used to examine and modify the bit masks.
  377.  
  378.  Because this manual presents the syntax of MS OS/2 system functions in
  379.  C-language syntax, it also defines bit masks in a way that is easiest to
  380.  work with using the C language: as a set of constant values. When a function
  381.  parameter is a bit mask, this manual provides a list of constants (named or
  382.  numeric) that represent the correct values used to set, clear, or examine
  383.  each field in the bit mask. For example, the fbType field of the VIOMODEINFO
  384.  structure in the VioSetMode function specifies three values:
  385.  VGMT_DISABLEBURST, VGMT_GRAPHICS, and VGMT_OTHER. These represent the "set"
  386.  values of the first three fields in the bit mask. Typically, the description
  387.  associated with the value explains the result of the function if the given
  388.  value is used (that is, when the corresponding bit is set). Generally, the
  389.  opposite result is assumed when the value is not used. For example, using
  390.  VGMT_GRAPHICS in the fbType field enables graphics mode; not using it
  391.  disables graphics mode.
  392.  
  393.  
  394.  1.2.5  Structures
  395.  
  396.  Many MS OS/2 system functions use structures as input and output parameters.
  397.  This manual defines all structures and their fields using C-language syntax.
  398.  In most cases, the structure definition presented is copied directly from
  399.  the C-language include files provided with the Microsoft C Optimizing
  400.  Compiler. Occasionally, an MS OS/2 function may have a structure that has no
  401.  corresponding include-file definition. In such cases, this manual gives an
  402.  incomplete form of the C-language structure definition to indicate that the
  403.  structure is not already defined in an include file.
  404.  
  405.  
  406.  1.3  Naming Conventions
  407.  
  408.  In this manual, all parameter, variable, structure, field, and constant
  409.  names conform to MS OS/2 naming conventions. MS OS/2 naming conventions are
  410.  rules that define how to create names that indicate both the purpose and
  411.  data type of an item used with MS OS/2 system functions. These naming
  412.  conventions are used in this manual to help you readily identify the purpose
  413.  and type of the function parameters and structure fields. These conventions
  414.  are also used in most MS OS/2 sample program sources to make the sources
  415.  more readable and informative.
  416.  
  417.  
  418.  1.3.1  Parameter and Field Names
  419.  
  420.  With MS OS/2 naming conventions, all parameter and field names consist of up
  421.  to three elements: a prefix, a base type, and a qualifier. A name always
  422.  consists of at least a base type or a qualifier. In most cases, the name
  423.  also includes a prefix.
  424.  
  425.  The base type, always written in lowercase letters, identifies the data type
  426.  of the item. The prefix, also written in lowercase letters, specifies
  427.  additional information about the item, such as whether it is a pointer, an
  428.  array, or a count of bytes. The qualifier, a short word or phrase written
  429.  with the first letter of each word uppercase, specifies the purpose of the
  430.  item.
  431.  
  432.  There are several standard prefixes and base types. These are used for the
  433.  data types most frequently used with MS OS/2.
  434.  
  435.  
  436.  1.3.1.1  Prefixes
  437.  
  438.  The following standard prefixes are used in MS OS/2 naming conventions:
  439.  
  440.  Prefix                            Description
  441.  ────────────────────────────────────────────────────────────────────────────
  442.  
  443.  p                                 Pointer. This prefix identifies a far,
  444.                                    or 32-bit, pointer to a given item. For
  445.                                    example, pch is a far pointer to a
  446.                                    character.
  447.  
  448.  np                                Near pointer. This prefix identifies a
  449.                                    near, or 16-bit, pointer to a given item.
  450.                                    For example, npch is a near pointer to a
  451.                                    character.
  452.  
  453.  a                                 Array. This prefix identifies an array
  454.                                    of two or more items of a given type.
  455.                                    For example, ach is an array of
  456.                                    characters.
  457.  
  458.  i                                 Index. This prefix identifies an index
  459.                                    into an array. For example, ich is an
  460.                                    index to one character in an array of
  461.                                    characters.
  462.  
  463.  c                                 Count. This prefix identifies a count of
  464.                                    items. It is usually combined with the
  465.                                    base type of the items being counted
  466.                                    instead of the base type of the actual
  467.                                    parameter. For example, cch is a count
  468.                                    of characters even though it may be
  469.                                    declared with the type USHORT.
  470.  
  471.  h                                 Handle. This prefix is used for values
  472.                                    that uniquely identify an object but
  473.                                    that cannot be used to access the object
  474.                                    directly. For example, hfile is a file
  475.                                    handle.
  476.  
  477.  off                               Offset. This prefix is used for values
  478.                                    that represent offsets from the
  479.                                    beginning of a buffer or a structure.
  480.                                    For example, off is the offset from the
  481.                                    beginning of the given segment to the
  482.                                    specified byte.
  483.  
  484.  id                                Identifier. This prefix is used for
  485.                                    values that identify an object. For
  486.                                    example, idSession is a session
  487.                                    identifier.
  488.  
  489.  
  490.  
  491.  1.3.1.2  Base Types
  492.  
  493.  The following standard base types are used in MS OS/2 naming conventions:
  494.  
  495.  Base type                         Type/Description
  496.  ────────────────────────────────────────────────────────────────────────────
  497.  
  498.  f                                 BOOL. A 16-bit flag or Boolean value.
  499.                                    The qualifier should describe the
  500.                                    condition associated with the flag when
  501.                                    it is TRUE. For example, fSuccess is
  502.                                    TRUE if successful and FALSE if not;
  503.                                    fError is TRUE if an error occurs and
  504.                                    FALSE if no error occurs. For objects of
  505.                                    type BOOL, a zero value implies FALSE, a
  506.                                    nonzero value implies TRUE.
  507.  
  508.  ch                                CHAR. An 8-bit signed value.
  509.  
  510.  s                                 SHORT. A 16-bit signed value.
  511.  
  512.  l                                 LONG. A 32-bit signed value.
  513.  
  514.  uch                               UCHAR. An 8-bit unsigned value.
  515.  
  516.  us                                USHORT. A 16-bit unsigned value.
  517.  
  518.  ul                                ULONG. A 32-bit unsigned value.
  519.  
  520.  b                                 BYTE. An 8-bit unsigned value. Same as
  521.                                    uch.
  522.  
  523.  sz                                CHAR[ ]. An array of characters,
  524.                                    terminated with a null character (the
  525.                                    last byte is set to zero).
  526.  
  527.  fb                                UCHAR. An array of flags in a byte. This
  528.                                    base type is used when more than one
  529.                                    flag is packed in an 8-bit value. Values
  530.                                    for such an array are typically created
  531.                                    by using the logical OR operator to
  532.                                    combine two or more values.
  533.  
  534.  fs                                USHORT. An array of flags in a short
  535.                                    (16-bit unsigned value). This base type
  536.                                    is used when more than one flag is
  537.                                    packed in a 16-bit value. Values for
  538.                                    such an array are typically created by
  539.                                    using the logical OR operator to combine
  540.                                    two or more values.
  541.  
  542.  fl                                ULONG. An array of flags in a long
  543.                                    (32-bit unsigned value). This base type
  544.                                    is used when more than one flag is
  545.                                    packed in a 32-bit value. Values for
  546.                                    such an array are typically created by
  547.                                    using the logical OR operator to combine
  548.                                    two or more values.
  549.  
  550.  sel                               SEL. A 16-bit value used to hold a
  551.                                    segment selector.
  552.  
  553.  
  554.  
  555.  The base type for a structure is usually derived from the structure name. An
  556.  MS OS/2 structure name, always written in uppercase letters, is a word or
  557.  phrase that describes the size, purpose, and/or intended content associated
  558.  with the type. The base type is typically an abbreviation of the structure
  559.  name. The following are some of the base types for the structures described
  560.  in this manual:
  561.  
  562.  avldt
  563.  cbnd
  564.  dena
  565.  eaop
  566.  efd
  567.  fat
  568.  fea
  569.  feal
  570.  findbuf2
  571.  flc
  572.  flr
  573.  fm
  574.  frwc
  575.  fsc
  576.  
  577.  fsinf
  578.  fsqbf
  579.  fsts2
  580.  fuc
  581.  fur
  582.  gea
  583.  geal
  584.  hci
  585.  hinit
  586.  ht
  587.  kbci
  588.  kbhw
  589.  ldtaddr
  590.  lis
  591.  
  592.  matlf
  593.  mlectl
  594.  mlefrd
  595.  mlemrg
  596.  mleovr
  597.  mlesrch
  598.  nmpsmst
  599.  param
  600.  pres
  601.  prfpro
  602.  progde
  603.  progt
  604.  progti
  605.  ptrcbf
  606.  
  607.  ptrdd
  608.  sbcd
  609.  stsdata
  610.  swblk
  611.  ti
  612.  viocreg
  613.  viofcsz
  614.  vioin
  615.  viomi
  616.  viosett
  617.  viosz
  618.  viouline
  619.  wprm
  620.  
  621.  
  622.  
  623.  
  624.  1.3.2  Constant Names
  625.  
  626.  A constant name is a descriptive name for a numeric value used with an MS
  627.  OS/2 function. All constant names are written in uppercase letters and have
  628.  a prefix derived from the name of the function, object, or idea associated
  629.  with the constant. The prefix is followed by an underscore (_) and the rest
  630.  of the constant name, which indicates the meaning of the constant and may be
  631.  a value, action, color, or condition. A few common constants do not have
  632.  prefixes─for example, NULL is used for null pointers of all types, and TRUE
  633.  and FALSE are used with the BOOL data type.
  634.  
  635.  
  636.  1.4  Notational Conventions
  637.  
  638.  
  639.  
  640.  The following notational conventions are used throughout this manual:
  641.  
  642.  Convention                        Meaning
  643.  ────────────────────────────────────────────────────────────────────────────
  644.  
  645.  bold                              Bold type is used for keywords─for
  646.                                    example, the names of functions, data
  647.                                    types, and structures. These names are
  648.                                    spelled exactly as they should appear in
  649.                                    source programs.
  650.  
  651.  italics                           Italic type is used to indicate the name
  652.                                    of an argument; this name must be
  653.                                    replaced by an actual argument. Italics
  654.                                    are also used to show emphasis in text.
  655.  
  656.  monospace                         Monospace type is used for example
  657.                                    program-code fragments.
  658.  
  659.  
  660.  
  661.  
  662.  
  663.  
  664.  
  665.  
  666.  Chapter 2  Overviews
  667.  ────────────────────────────────────────────────────────────────────────────
  668.  
  669.  
  670.  
  671.  
  672.  2.1  Introduction
  673.  
  674.  This chapter describes the MS OS/2 system functions in individual-topic
  675.  sections. Each section describes a portion of MS OS/2 that lets an
  676.  application carry out a specific task or set of related tasks. For example,
  677.  the section about the multiple-line entry field (MLE) defines basic MLE
  678.  terms, describes the role of multiple-line entry-field messages, and
  679.  illustrates how to use those messages.
  680.  
  681.  Each topic section in this chapter gives a general description and
  682.  programming samples. Each section discusses the purpose and operation of the
  683.  pertinent MS OS/2 functions. The programming samples show how to use those
  684.  functions in applications to carry out useful tasks.
  685.  
  686.  In many cases, it is assumed that you have basic knowledge of some other
  687.  portions of MS OS/2. Each section lists the prerequisites for understanding
  688.  the concepts and terms described in that section.
  689.  
  690.  
  691.  2.2  Installable File Systems
  692.  
  693.  This section describes how MS OS/2 enables applications to use installable
  694.  file systems. A file system is the combination of software and hardware that
  695.  supports storing information on a storage device. An installable file system
  696.  is a file system whose software can be installed when the operating system
  697.  starts. MS OS/2 supports installable file systems and permits users to have
  698.  multiple file systems active at the same time.
  699.  
  700.  This section also describes some of the MS OS/2 functions that enable
  701.  applications to create, read, and write data files in installable file
  702.  systems. Because installable file systems are not available with releases of
  703.  MS OS/2 earlier than version 1.2 or with MS-DOS versions 2.0 through 3.3,
  704.  applications that use the family application programming interface (family
  705.  API) cannot use functions that are specific to installable file systems.
  706.  
  707.  
  708.  2.2.1  About Installable File Systems
  709.  
  710.  In MS OS/2 versions 1.2 and later, users install a file system by specifying
  711.  the file-system components in the config.sys file. The file-system software
  712.  consists of device drivers that access storage devices and dynamic-link
  713.  libraries that control the format of information on a device and manage the
  714.  flow of data to and from the device. The user must use the device command to
  715.  specify the device driver and the ifs command to specify the dynamic-link
  716.  library. MS OS/2 loads the device driver and dynamic-link library and
  717.  initializes a specific device for use as a file system.
  718.  
  719.  MS OS/2 versions 1.2 and later have two file systems: the file allocation
  720.  table (FAT) file system and the high-performance file system (HPFS). These
  721.  file systems define how information is organized on the storage devices.
  722.  Both file systems create data files supported by one or more tables that
  723.  specify the location and size of the data files on the storage device.
  724.  
  725.  The file allocation table (FAT) file system is the default file system for
  726.  MS OS/2; it does not need to be installed. The FAT file system, used in
  727.  previous releases of MS OS/2 and also in MS-DOS, controls storage of data
  728.  files for fixed and floppy disks. The FAT file system is hierarchical,
  729.  allowing multiple directories on the disk. Each directory can contain one or
  730.  more files. The distinguishing feature of the FAT file system is its 8.3
  731.  filename convention. Under this convention, the filename consists of a
  732.  filename (up to eight characters), a separating period (.), and a filename
  733.  extension (up to three characters).
  734.  
  735.  The high-performance file system (HPFS) is an installable file system for MS
  736.  OS/2. It is an hierarchical file system and allows for multiple directories.
  737.  HPFS controls storage of data for fixed disks. Filenames under HPFS can be
  738.  any practical length and can contain characters that are not valid for the
  739.  FAT file system, for example, spaces and underscores (__). In many cases,
  740.  accessing files under HPFS is faster than accessing similar files under the
  741.  FAT file system.
  742.  
  743.  A user can choose either or both file systems. Applications must be able to
  744.  work with any file system. Fortunately, MS OS/2 provides a common set of
  745.  file-system functions that are not dependent upon a particular file system;
  746.  it also gives guidelines for working with file systems, such as specific
  747.  filename conventions.
  748.  
  749.  
  750.  2.2.1.1  File-System Functions
  751.  
  752.  MS OS/2 provides a standard set of file-system functions. This means that
  753.  applications can create, open, read, write, copy, and delete files and
  754.  directories by using the same functions, regardless of which file system is
  755.  used. When an application calls a file-system function, MS OS/2 passes the
  756.  request to the dynamic-link library that supports the file system. Most
  757.  file-system processing, such as validating filenames, is carried out by the
  758.  dynamic-link library. If an error occurs, the file system returns the error
  759.  to MS OS/2, which then passes the error back to the calling application.
  760.  
  761.  Occasionally, a file system may extend the standard set of file-system
  762.  functions by providing file-system control functions. The control functions
  763.  are specific to the given file system. An application can call a control
  764.  function by using the DosFSCtl function, which directs MS OS/2 to pass the
  765.  control-function information to the dynamic-link library for the particular
  766.  file system.
  767.  
  768.  
  769.  2.2.1.2  Volumes
  770.  
  771.  MS OS/2 allows more than one file system on a single storage device. If the
  772.  device can have more than one logical partition (or volume), each partition
  773.  can be initialized as an MS OS/2 partition and given a valid MS OS/2 file
  774.  system. For each volume, MS OS/2 determines the type of file system the
  775.  first time the volume is accessed by a function or when the medium in the
  776.  drive changes. After that, MS OS/2 manages all input and output to that
  777.  volume by using the corresponding dynamic-link library for the file system.
  778.  
  779.  MS OS/2 uses the volume label and serial number to ensure that the medium in
  780.  the drive does not change while there are outstanding requests for input and
  781.  output. Each volume has a volume label and a 32-bit volume serial number,
  782.  stored in a reserved location in logical sector zero at the time of
  783.  formatting. If the volume label and serial number do not match, MS OS/2
  784.  signals the critical-error handler to prompt the user to insert the volume
  785.  that has the specified serial number and label. MS OS/2 maintains the
  786.  connection between the medium and the volume label and serial number until
  787.  all open files on the volume are closed and all search references and
  788.  cache-buffer references are removed. The system redetermines the type of the
  789.  file system and the volume label and serial number for the volume only when
  790.  the medium changes.
  791.  
  792.  
  793.  2.2.1.3  Local and Remote File Systems
  794.  
  795.  Installable file systems work with a variety of storage devices. A file
  796.  system on a local device such as a disk drive or virtual disk is called a
  797.  local file system. A file system on a remote device such as a disk drive on
  798.  another computer is called a remote file system. An application can
  799.  establish a connection to a local or a remote file system by using the
  800.  DosFSAttach function.
  801.  
  802.  For a local file system, MS OS/2 uses a block device driver to handle input
  803.  and output to the device. MS OS/2 automatically connects most (if not all)
  804.  local file systems when it starts. However, an application can connect and
  805.  disconnect (sometimes called mount and dismount) additional file systems as
  806.  needed.
  807.  
  808.  For a remote file system, the corresponding device driver typically accesses
  809.  a communications or network device instead of a block device driver used to
  810.  access disk hardware. Typically, the actual storage device is located on
  811.  another computer, and the two computers communicate requests and data
  812.  through a network connection. An application can connect a remote file
  813.  system to a drive letter by using the DosFSAttach function. Once the
  814.  connection is made, the application can access directories and files on the
  815.  remote device simply by using the assigned drive letter, treating the remote
  816.  device as if it were on the same computer.
  817.  
  818.  
  819.  2.2.1.4  Pseudo-Character Devices
  820.  
  821.  An application can attach a device name to a file system and use the file
  822.  system as a pseudo-character device (also called a single-file device).
  823.  Attaching a device name to a file system lets an application open the device
  824.  associated with the file system as if it were a character device (for
  825.  example, a serial port) and read from and write to the device by using the
  826.  DosRead and DosWrite functions. Unlike with a character device, an
  827.  application can use the DosChgFilePtr and DosFileLocks functions for working
  828.  with a pseudo-character device. An MS OS/2 pseudo-character device name is a
  829.  null-terminated string in the format of an MS OS/2 filename in a
  830.  subdirectory called \edev.
  831.  
  832.  A file system that can be attached to a pseudo-character device is typically
  833.  associated with a single disk file or with a special storage device such as
  834.  a tape drive. The file system establishes a connection with the device and
  835.  transfers requests and data between MS OS/2 and the device. The following
  836.  example attaches the device associated with the file system cabinet1 to the
  837.  pseudo-character device named \edev\ehost:
  838.  
  839.  BYTE bData[];
  840.  USHORT cbData;
  841.  
  842.  DosFSAttach("\dev\host", "cabinet1", bData, cbData, 0);
  843.  
  844.  
  845.  
  846.  
  847.  If the application successfully attaches the file system, the application
  848.  can then open the file \edev\ehost by using the DosOpen function, read
  849.  host-created data by using the DosRead function, and write data and commands
  850.  to the host by using the DosWrite function. This example assumes that the
  851.  name cabinet1 corresponds to an installable file system and that the file
  852.  system can perform the necessary host communication and translation.
  853.  
  854.  
  855.  2.2.1.5  Filename Conventions
  856.  
  857.  Filename conventions are the rules used to form names that uniquely identify
  858.  files in a given file system. Although each installable file system can have
  859.  specific rules about how individual components in a directory or filename
  860.  are formed, all file systems follow the same general conventions for
  861.  combining components. For example, the FAT file system requires that file
  862.  and directory names have the 8.3 filename format, HPFS allows names to be
  863.  any length, but both file systems use the backslash (\e) character to
  864.  separate directory names and the filename when forming a path.
  865.  
  866.  When creating names for directories and files or when processing names
  867.  supplied by the user, applications should follow these general rules:
  868.  
  869.    1.  Process a path as a null-terminated string. An application can
  870.        determine maximum length for a path by using the DosQSysInfo function.
  871.  
  872.    2.  Use any character in the current code page for a name, but do not use
  873.        a path separator, a character in the range 0 through 31, or any
  874.        character explicitly disallowed by the file system. Although a name
  875.        can contain characters above 127, an application must be able to
  876.        switch code pages if necessary to access the corresponding file.
  877.  
  878.    3.  Compare names using a case-insensitive comparison. Names such as ABC,
  879.        Abc, and abc are considered to be the same name.
  880.  
  881.    4.  Use the backslash (\e) and/or the forward slash (/) to separate
  882.        components in a path. No other character is accepted as a path
  883.        separator.
  884.  
  885.    5.  Use the dot (.) as a directory component in a path to represent the
  886.        current directory.
  887.  
  888.    6.  Use two dots (..) as a directory component in a path to represent the
  889.        parent of the current directory.
  890.  
  891.    7.  Use a period (.) to separate components in a directory name or
  892.        filename. Unless explicitly defined by a file system, there are no
  893.        restrictions on the number of components in a name.
  894.  
  895.  
  896.  
  897.  
  898.  2.2.1.6  Filenames in DOS-Compatibility Mode
  899.  
  900.  For compatibility with existing DOS 3.x applications, all file systems
  901.  support the FAT file system's 8.3 filename format. This means that
  902.  applications running in DOS-compatibility mode can access files on non-FAT
  903.  file systems if the filenames have the 8.3 format. To guarantee this rule,
  904.  MS OS/2 automatically applies the 8.3 truncation rules to all filenames
  905.  given in file-system requests from DOS-compatibility mode.
  906.  
  907.  
  908.  2.2.1.7  Filenames in User Input
  909.  
  910.  Users often supply filenames as part of an application's command line or in
  911.  response to a prompt from the application. Traditionally, users have been
  912.  able to supply more than one filename on the command line or in a prompt by
  913.  separating the names with certain characters, such as a blank space. In some
  914.  file systems, however, traditional separators can be used as valid filename
  915.  characters. This means that some additional conventions are required to
  916.  ensure that an application processes all characters in a name.
  917.  
  918.  When an application processes arguments (including filenames) from its
  919.  command line, the application should treat the double quotation mark (") and
  920.  the caret (^) as quotation characters. All characters between the starting
  921.  and closing double quotation marks should be processed as a single argument.
  922.  The character immediately following the caret should be processed as part of
  923.  the current argument. In both cases, the quotation characters are discarded
  924.  and not treated as part of the final argument.
  925.  
  926.  When an application processes two or more filenames from a dialog box or
  927.  other prompt, it expects the user to enter each filename on a new line. For
  928.  example, a Presentation Manager application should use a multiple-line entry
  929.  field to prompt for multiple filenames. This makes the use of quotation
  930.  characters unnecessary.
  931.  
  932.  When an application is started from File Manager, File Manager may construct
  933.  a command line for the application. If the command line includes filenames,
  934.  File Manager separates each argument with a space character and marks the
  935.  end of the argument list with two null characters. Applications that start
  936.  other applications by using the DosExecPgm function also can pass arguments
  937.  using this convention or by using quotation characters. In practice, most
  938.  applications receive a command line as a single, null-terminated string.
  939.  Therefore, applications that use the DosExecPgm function should prepare
  940.  command lines as a single string with any filenames in the string enclosed
  941.  in quotation marks.
  942.  
  943.  
  944.  2.2.1.8  Metacharacters in Filenames
  945.  
  946.  To give the user a shortcut to entering long lists of names, applications
  947.  that accept more than one filename on their command line can allow
  948.  metacharacters in filenames. The metacharacters, the asterisk (*) and the
  949.  question mark (?), represent placeholders in a filename. Although a name
  950.  that contains metacharacters is not a complete filename, an application can
  951.  use functions, such as DosFindFirst and DosEditName, to expand the name
  952.  (replace the metacharacters) to create one or more valid filenames.
  953.  
  954.  An application can expand a name with metacharacters to a list of filenames
  955.  by using the DosFindFirst function. The asterisk (*) matches one or more
  956.  characters, including blanks. The question mark (?) matches one character,
  957.  unless that character is a period (.). To match a period, the original name
  958.  must contain a period.
  959.  
  960.  An application can create a new filename from an existing name by using the
  961.  DosEditName function. This function takes a template (a name with
  962.  metacharacters) and expands it, using characters from an existing name. An
  963.  asterisk (*) in the template directs the function to copy all characters in
  964.  the existing name until it locates a character that matches the character
  965.  following the asterisk. A question mark (?) directs the function to copy one
  966.  character unless that character is a period. The period (.) in the template
  967.  directs the function look for and move to the next period in the existing
  968.  name, skipping any characters between the current position and the period.
  969.  
  970.  The metacharacters are illegal in all but the last component of a path.
  971.  
  972.  
  973.  2.2.1.9  File-System Errors
  974.  
  975.  Some MS OS/2 file-system functions return the following errors:
  976.  
  977.  Value                             Meaning
  978.  ────────────────────────────────────────────────────────────────────────────
  979.  
  980.  ERROR_WRITE_PROTECT               The disk in the drive is write-protected.
  981.  
  982.  ERROR_BAD_UNIT                    There is a breakdown of internal
  983.                                    consistency in mapping between the
  984.                                    logical drive and the device driver.
  985.                                    Internal error.
  986.  
  987.  ERROR_NOT_READY                   The device is not ready.
  988.  
  989.  ERROR_BAD_COMMAND                 There is a breakdown of internal
  990.                                    consistency between the expected
  991.                                    capability of a device driver and its
  992.                                    true capability.
  993.  
  994.  ERROR_CRC                         The device driver detected a cyclic
  995.                                    redundancy check (CRC) mismatch.
  996.  
  997.  ERROR_BAD_LENGTH                  There is a breakdown of internal
  998.                                    consistency between the expected length
  999.                                    of a request packet and the true length.
  1000.                                    Internal error.
  1001.  
  1002.  ERROR_SEEK                        The device driver detected an error
  1003.                                    during a seek operation.
  1004.  
  1005.  ERROR_NOT_DOS_DISK                The disk is not recognized as being
  1006.                                    manageable by MS OS/2.
  1007.  
  1008.  ERROR_SECTOR_NOT_FOUND            The device is unable to find the
  1009.                                    specific sector.
  1010.  
  1011.  ERROR_OUT_OF_PAPER                The printer is out of paper.
  1012.  
  1013.  ERROR_WRITE_FAULT                 Other write-specific error.
  1014.  
  1015.  ERROR_READ_FAULT                  Other read-specific error.
  1016.  
  1017.  ERROR_GEN_FAILURE                 Other error.
  1018.  
  1019.  
  1020.  
  1021.  There are also errors defined by and specific to the specific device driver.
  1022.  These are indicated by either 0xFF or 0xFE in the high byte of the error
  1023.  code.
  1024.  
  1025.  
  1026.  2.2.2  Summary
  1027.  
  1028.  The following MS OS/2 file-system functions work with installable file
  1029.  systems:
  1030.  
  1031.  DosCopy  Copies a file or subdirectory.
  1032.  
  1033.  DosEditName  Transforms a source string using an editing string.
  1034.  
  1035.  DosFileIO  Performs file I/O (locking, unlock, seek, read, and write
  1036.  operations).
  1037.  
  1038.  DosFindFirst2  Finds the first file that matches a specified filename and
  1039.  attributes.
  1040.  
  1041.  DosFSAttach  Attaches or detaches a drive or pseudo-character device from a
  1042.  remote file system.
  1043.  
  1044.  DosFSCtl  Calls file-system functions that are not part of the standard I/O
  1045.  functions.
  1046.  
  1047.  DosGetResource2  Retrieves a resource for a module.
  1048.  
  1049.  DosMkDir2  Creates a directory.
  1050.  
  1051.  DosOpen2  Opens or creates a file with extended attributes.
  1052.  
  1053.  DosQFSAttach  Queries information about an attached file system.
  1054.  
  1055.  DosSetPathInfo  Sets information for a file or directory.
  1056.  
  1057.  DosShutdown  Shuts down the file system.
  1058.  
  1059.  
  1060.  2.3  Extended Attributes
  1061.  
  1062.  This section describes how to use extended attributes to store information
  1063.  about your files and directories. Before reading this section, you should be
  1064.  familiar with the MS OS/2 file system.
  1065.  
  1066.  
  1067.  2.3.1  About Extended Attributes
  1068.  
  1069.  Extended attributes can be thought of as a list of facts attached to a file
  1070.  or directory. MS OS/2 stores extended attributes separate from the file or
  1071.  directory so that the attributes do not affect the contents of the file or
  1072.  directory. An application uses extended attributes to provide a description
  1073.  of the file or directory, but does not place the description in the file or
  1074.  directory itself.
  1075.  
  1076.  Each extended attribute has two parts: a name and a value. The name is a
  1077.  null-terminated string; applications can choose any convenient name. The
  1078.  value is corresponding data; it can be text, a bitmap, or any binary data.
  1079.  The application that creates the extended attributes and the applications
  1080.  that read the extended attributes must recognize the format and meaning of
  1081.  the data associated with a given name.
  1082.  
  1083.  
  1084.  2.3.2  Using Extended Attributes
  1085.  
  1086.  Applications can examine, add, and replace extended attributes at any time.
  1087.  The DosOpen2 function adds extended attributes to new or existing files; the
  1088.  DosMkDir2 function adds extended attributes to new directories. Any
  1089.  application can read the extended attributes by using the DosQFileInfo or
  1090.  DosQPathInfo function. Applications can also search for files that have
  1091.  specific extended attributes by using the DosFindFirst and DosFindNext
  1092.  functions.
  1093.  
  1094.  A file can have any number of extended attributes. Each extended attribute
  1095.  can be up to 64K long. For MS OS/2 versions 1.2 and later, the sum of all
  1096.  extended attributes for a file must not exceed 64K.
  1097.  
  1098.  
  1099.  2.3.2.1  Naming Conventions
  1100.  
  1101.  Although an application can choose any name for the extended attributes it
  1102.  creates, other applications cannot read the extended attributes unless they
  1103.  also recognize the corresponding format. Because many applications use
  1104.  extended attributes consisting of text, bitmaps, and other similar data, a
  1105.  set of names has been adopted to help identify these formats when used in
  1106.  extended attributes. An application need not be limited to this set of
  1107.  standard extended attributes but should use it as a way for many
  1108.  applications to access a common set of information.
  1109.  
  1110.  The names for all standard extended attributes use a dot (.) as a prefix.
  1111.  The leading dot is considered reserved, so no application should define
  1112.  extended attributes that start with a dot. Also, extended attributes that
  1113.  start with the characters $, @, &, and + are reserved for system use. To
  1114.  ensure that its extended attributes are unique, an application should use
  1115.  the vendor and application name as a prefix for application-specific
  1116.  extended attributes. For example, Microsoft Excel would use MS
  1117.  EXCEL.MYSTUFF, MS EXCEL.MORESTUFF, and so forth.
  1118.  
  1119.  
  1120.  2.3.2.2  Data-Type Conventions
  1121.  
  1122.  Extended attributes can contain any type of data. To identify the type of
  1123.  information, the first word of extended-attribute data should specify one of
  1124.  the following data types:
  1125.  
  1126.  Value                             Meaning
  1127.  ────────────────────────────────────────────────────────────────────────────
  1128.  
  1129.  EAT_BINARY                        Binary data; the first word specifies
  1130.                                    length.
  1131.  
  1132.  EAT_ASCII                         ASCII text; the first word specifies
  1133.                                    length.
  1134.  
  1135.  EAT_BITMAP                        Bitmap data; the first word specifies
  1136.                                    length.
  1137.  
  1138.  EAT_METAFILE                      Metafile data; the first word specifies
  1139.                                    length.
  1140.  
  1141.  EAT_ICON                          Icon data; the first word specifies
  1142.                                    length.
  1143.  
  1144.  EAT_EA                            ASCII name of associated data; the first
  1145.                                    word specifies length.
  1146.  
  1147.  EAT_MVMT                          Two or more consecutive
  1148.                                    extended-attribute values; each value
  1149.                                    has an explicitly specified type.
  1150.  
  1151.  EAT_MVST                          Two or more consecutive
  1152.                                    extended-attribute values; all values
  1153.                                    have the same type.
  1154.  
  1155.  EAT_ASN1                          ASN.1 field data.
  1156.  
  1157.  
  1158.  
  1159.  In all cases, the length specifies the number of bytes of data. Other values
  1160.  for data types, in the range 0x0000 through 0x7FFF, can be used for
  1161.  user-defined extended attributes. User-defined data should also specify the
  1162.  length.
  1163.  
  1164.  For example, here is how to represent the string "Hello":
  1165.  
  1166.  EAT_ASCII               0005            Hello
  1167.  
  1168.  
  1169.  
  1170.  
  1171.  
  1172.  2.3.3  Standard Extended Attributes
  1173.  
  1174.  The standard extended attributes are listed in the following sections. The
  1175.  field format follows the data-type conventions given previously. A field can
  1176.  be a multivalue or single-value field.
  1177.  
  1178.  
  1179.  2.3.3.1  .TYPE
  1180.  
  1181.  The .TYPE extended attribute indicates the type of file. It is similar to
  1182.  the earlier use of filename extensions. The following file types are
  1183.  predefined:
  1184.  
  1185.  Plain Text
  1186.  OS/2 Command File
  1187.  DOS Command File
  1188.  Executable
  1189.  Metafile
  1190.  Bitmap
  1191.  Icon
  1192.  Binary Data
  1193.  Dynamic-Link Library
  1194.  C Code
  1195.  Pascal Code
  1196.  BASIC Code
  1197.  COBOL Code
  1198.  FORTRAN Code
  1199.  Assembler Code
  1200.  Library
  1201.  Resource File
  1202.  
  1203.  
  1204.  
  1205.  
  1206.  Applications can use their own type names, such as Microsoft Excel Chart.
  1207.  The first words in the type name should be the name of the vendor and the
  1208.  application. For example, Microsoft Excel Chart, Microsoft Excel Worksheet,
  1209.  Lotus 1-2-3 Spreadsheet.
  1210.  
  1211.  Entries should be ASCII. Case is important.
  1212.  
  1213.  The performance of extended attributes is dependent on the file system.
  1214.  Because some file systems store extended attributes in first-in/first out
  1215.  (FIFO) order, it is important to write the .TYPE entry first so that File
  1216.  Manager can access that information quickly.
  1217.  
  1218.  
  1219.  2.3.3.2  .KEYPHRASES
  1220.  
  1221.  The .KEYPHRASES extended attribute specifies text key phrases for the file.
  1222.  Such phrases can be used for a database-style search or to help the user
  1223.  understand the nature of the file.
  1224.  
  1225.  If there is more than one key phrase, each should be stored in a separate
  1226.  entry in a multivalue field. Each entry should be ASCII.
  1227.  
  1228.  
  1229.  2.3.3.3  .SUBJECT
  1230.  
  1231.  The .SUBJECT extended attribute contains a brief summary of the file's
  1232.  content and/or purpose. This attribute should be less than 40 characters
  1233.  long.
  1234.  
  1235.  This field should be a single-value ASCII entry.
  1236.  
  1237.  
  1238.  2.3.3.4  .COMMENTS
  1239.  
  1240.  The file. It can be a multivalue field and be of any type. This field is
  1241.  intended as a reminder note. For example, it could contain some notes about
  1242.  the intent of a file or a picture.
  1243.  
  1244.  
  1245.  2.3.3.5  .HISTORY
  1246.  
  1247.  The .HISTORY extended attribute lists the history of a file's modification.
  1248.  It lists the author of the file and all subsequent changes. Each action
  1249.  entry should be a separate field in a multivalue field. Each entry should be
  1250.  ASCII.
  1251.  
  1252.  The application can let the user decide when an entry is placed into the
  1253.  history field, to avoid unnecessary file growth. For example, there are some
  1254.  cases when it is important to note when a document is printed; however, it
  1255.  is probably unnecessary to note every time the file was printed.
  1256.  
  1257.  
  1258.  2.3.3.6  .VERSION
  1259.  
  1260.  The
  1261.  
  1262.  example, Excel Worksheet 1).
  1263.  
  1264.  This attribute should be ASCII or binary. It should be modified only by the
  1265.  application. This attribute can also be used to indicate an application or
  1266.  dynamic-link library version.
  1267.  
  1268.  
  1269.  2.3.3.7  .ICON
  1270.  
  1271.  The   «ON EXTENDED ATTRIBUTE SPECIFIES THE ICON TO BE USED FOR THE FILE»
  1272.  
  1273.  representation, whether in File Manager or when minimized. File Manager can
  1274.  use the .TYPE entry to determine the default application to run and to
  1275.  determine the default icon for that type of file. If there is a   «ON
  1276.  ENTRY,»
  1277.  
  1278.  however, it is used instead of the icon associated with a particular type.
  1279.  
  1280.  If the data type is for an icon, the icon data follows. It is best to
  1281.  provide as much icon information as possible. Ideally, an icon should be
  1282.  64-by-64 bits in 8-color, device-independent format.
  1283.  
  1284.  Executable files should simply store the binary icon data in this extended
  1285.  attribute. They should use the .ASSOCTABLE extended attribute to install
  1286.  icons for data files.
  1287.  
  1288.  
  1289.  2.3.3.8  .ASSOCTABLE
  1290.  
  1291.  The .ASSOCTABLE extended attribute contains association data for a file. It
  1292.  is created by the Microsoft Operating System/2 Resource Compiler (rc), from
  1293.  a table with the following form:
  1294.  
  1295.  ASSOCTABLE assoctable -id
  1296.  BEGIN
  1297.          "type name", "extension", [flags], [icon filename]
  1298.          .
  1299.          .
  1300.  END
  1301.  
  1302.  
  1303.  
  1304.  
  1305.  The .ASSOCTABLE extended attribute contains information that associates
  1306.  icons with the data files an application creates. The file-association table
  1307.  associates icons by data type.
  1308.  
  1309.  The .ASSOCTABLE extended attribute allows an application to indicate the
  1310.  type, extension, and icon for the data files it recognizes. It also contains
  1311.  an ownership flag. This data can be installed automatically by File Manager.
  1312.  
  1313.  
  1314.  For example, the table for Microsoft Excel could be:
  1315.  
  1316.  "MS Excel Worksheet", "XLS", AF_DEFAULTOWNER, excel.sheet.icon
  1317.  "MS Excel Chart", "XLC", AF_DEFAULTOWNER, excel.chart.icon
  1318.  
  1319.  
  1320.  
  1321.  
  1322.  The flag entry indicates if the application owns or merely recognizes the
  1323.  type. The icon file contains an icon for that data type.
  1324.  
  1325.  
  1326.  2.3.3.9  .HPFSNAME
  1327.  
  1328.  The FSNAME attribute is used when an application attempts to write a file
  1329.  with a long name to a file system that does not support long names. The
  1330.  application should generate a unique short name for the file and notify the
  1331.  user of the new short name. It should then save the original (long) filename
  1332.  in the .HPFSNAME extended attribute.
  1333.  
  1334.  When a file is copied from a system that uses short names to a system that
  1335.  uses long names, the application should check the .HPFSNAME extended
  1336.  attribute. If a value is present, the application should allow the file to
  1337.  be renamed to a long name. The .HPFSNAME extended attribute should then be
  1338.  removed.  To support extended attributes, applications should do the
  1339.  following:
  1340.  
  1341.    1.  Fill in the .ASSOCTABLE extended attribute for all major file types
  1342.        that the application recognizes or uses.
  1343.  
  1344.    2.  Fill in the «ON EXTENDED ATTRIBUTE FOR EXECUTABLE FILES.»
  1345.  
  1346.    3.  Set the .TYPE field for data files it creates.
  1347.  
  1348.    4.  Fill in and use the FSNAME extended attribute as appropriate.
  1349.  
  1350.    5.  Support .HISTORY and
  1351.  
  1352.        Support the other standard extended attributes as appropriate.
  1353.        In many cases, extended attributes need to store more than a single
  1354.        piece of information. For example, an extended attribute can store a
  1355.        list of the names of people to whom a mail document was sent. The
  1356.        multivalue formats specify how individual pieces of data are stored.
  1357.  
  1358.  
  1359.  
  1360.  In a multivalue field, the first entry in the list is assumed to be the
  1361.  default. For example, suppose the .TYPE entry contains Text and C Code. Text
  1362.  is the default type. If C Code is the first entry in the list (C Code and
  1363.  Text), then C Code is the default type.
  1364.  
  1365.  
  1366.  2.3.3.10  Multivalue, Multitype Attributes
  1367.  
  1368.  The EAT_MVMT type allows a single extended attribute to contain several
  1369.  pieces of information; each piece of information can be a different type.
  1370.  
  1371.  
  1372.  2.3.3.11  Multivalue, Single-Type Attributes
  1373.  
  1374.  The EAT_MVST type sets up a multivalue field in which each piece of
  1375.  information is of the same type.
  1376.  
  1377.  
  1378.  2.3.3.12  ASN.1
  1379.  
  1380.  The EAT_ASN1 type is an ISO standard for describing multivalue data streams.
  1381.  
  1382.  
  1383.  
  1384.  2.3.3.13  Include-Extended-Attribute Type
  1385.  
  1386.  The EAT_EA type indicates that the data is continued in another
  1387.  extended-attribute entry associated with the file. Among other things, this
  1388.  allows for extended attributes greater than 64K (but not exceeding the limit
  1389.  per file).
  1390.  
  1391.  
  1392.  2.3.4  Summary
  1393.  
  1394.  The following MS OS/2 functions create and manage extended attributes:
  1395.  
  1396.  DosFindFirst2  Finds the first file that matches the specified filename and
  1397.  attributes.
  1398.  
  1399.  DosMkDir2  Creates a directory.
  1400.  
  1401.  DosOpen2  Opens or creates a file with extended attributes.
  1402.  
  1403.  DosQFileInfo  Retrieves file information, including the date and time the
  1404.  file was created, the date and time it was last accessed, the date and time
  1405.  it was last written to, its size, and its attributes. It also returns
  1406.  information about a file's extended attributes.
  1407.  
  1408.  DosQPathInfo  Retrieves information about a file or directory.
  1409.  
  1410.  DosSetFileInfo  Sets file information, including the date and time the file
  1411.  was created, the date and time it was last accessed, the date and time it
  1412.  was last written to, the size of the file, and its attributes. It can also
  1413.  set extended attributes for a file.
  1414.  
  1415.  DosSetPathInfo  Sets information for a file or directory.
  1416.  
  1417.  
  1418.  2.4  Profile Manager
  1419.  
  1420.  This section describes how to use the MS OS/2 Profile Manager to store and
  1421.  retrieve information about your application and the system from the MS OS/2
  1422.  initialization files. Before reading this section, you should be familiar
  1423.  with the MS OS/2 initialization files.
  1424.  
  1425.  Profile Manager functions replace the MS OS/2 initialization-file functions
  1426.  described in the Microsoft Operating System/2 Programmer's Reference, Volume
  1427.  1.
  1428.  
  1429.  
  1430.  2.4.1  About Profile Manager
  1431.  
  1432.  Profile Manager enables applications to create their own initialization
  1433.  files and to access the MS OS/2 initialization files, os2.ini and
  1434.  os2sys.ini. An initialization file is a convenient place to store
  1435.  information between sessions. Just as MS OS/2 uses the os2.ini and
  1436.  os2sys.ini files to store configuration information for when it starts, an
  1437.  application can create initialization files that store information it uses
  1438.  to initialize windows and data when it starts.
  1439.  
  1440.  Because all initialization files are binary files, the user cannot view or
  1441.  edit them directly. A file consists of one or more sections; each section
  1442.  contains one or more settings, or keys. Each key consists of two parts: a
  1443.  name and a value. Both section names and key names are null-terminated
  1444.  strings. A key value can be a null-terminated string, a null-terminated
  1445.  string representing a signed integer, or individual bytes of data.
  1446.  
  1447.  The MS OS/2 initialization files, os2.ini and os2sys.ini, contain sections
  1448.  and settings used by the MS OS/2-system applications (such as Desktop
  1449.  Manager, Control Panel, and Print Manager). Although applications can read
  1450.  settings from the MS OS/2 initialization files, only rarely will an
  1451.  application need to change a setting. One common task that does change the
  1452.  settings in the MS OS/2 initialization files is adding a group and program
  1453.  list to Desktop Manager. For example, the installation program for an
  1454.  application can create a new group for the application and its related
  1455.  utilities by using Profile Manager functions.
  1456.  
  1457.  Once an initialization file is created, an application can rename, copy,
  1458.  move, and delete the file just like any other file. Although an application
  1459.  can also read and write to the file as if it were a binary file, the
  1460.  application should always use Profile Manager functions to access the
  1461.  contents of the file.
  1462.  
  1463.  
  1464.  2.4.2  Using Profile Manager
  1465.  
  1466.  You can use Profile Manager functions in character-based MS OS/2 programs as
  1467.  well as in Presentation Manager applications. A thread that calls Profile
  1468.  Manager functions must have initialized an anchor block by using the
  1469.  WinInitialize function. You create an initialization file or open an
  1470.  existing one by using the PrfOpenProfile function. You then store and
  1471.  retrieve information from the file by using functions such as
  1472.  PrfQueryProfileString and PrfWriteProfileString. You can also create and
  1473.  manage groups and program lists by using functions such as PrfAddProgram and
  1474.  PrfCreateGroup.
  1475.  
  1476.  
  1477.  2.4.2.1  Creating or Opening an Initialization File
  1478.  
  1479.  You can create an initialization file or open an existing initialization
  1480.  file by using the PrfOpenProfile function. This function takes a handle to
  1481.  an anchor block and a pointer to the name of an initialization file. If the
  1482.  file doesn't exist in the given path, the function automatically creates an
  1483.  initialization file.
  1484.  
  1485.  The following example creates an initialization file named pmtools.ini in
  1486.  the current directory:
  1487.  
  1488.  HAB hab;
  1489.  HINI hini;
  1490.  
  1491.  hab = WinInitialize(0);
  1492.      /* initialization file not opened or created */
  1493.  
  1494.  
  1495.  
  1496.  
  1497.  If it is successful, the PrfOpenProfile function returns a handle to the
  1498.  initialization file. Otherwise, it returns NULL. Once you have an
  1499.  initialization-file handle, you can create new sections in the file and make
  1500.  new settings.
  1501.  
  1502.  To close an initialization file, you use the PrfCloseProfile function.
  1503.  
  1504.  
  1505.  2.4.2.2  Reading and Writing Settings
  1506.  
  1507.  You can read and write strings, integers, and binary data to and from an
  1508.  initialization file. To read from or write to an initialization file, you
  1509.  must provide a section and a key name that specifies which setting to read
  1510.  or to change. When you write to an initialization file, if there is no
  1511.  corresponding section and/or key name, the section and/or key name is added
  1512.  to the file and assigned the given value.
  1513.  
  1514.  The following example creates the section "MyApp" and the key name
  1515.  "MainWindowColor" in a previously opened initialization file and assigns the
  1516.  value of the RGB structure to the new setting:
  1517.  
  1518.  HINI hini;
  1519.  RGB rgb = { 0xFF, 0x00, 0x00 };
  1520.  
  1521.  PrfWriteProfileData(hini, "MyApp", "MainWindowColor", &rgb, sizeof(RGB));
  1522.  
  1523.  To read a setting, you can retrieve the size of the setting and then read
  1524.  the setting into an appropriate buffer by using the PrfQueryProfileSize and
  1525.  PrfQueryProfileData functions, as shown in the following example. This
  1526.  example reads the setting "MainWindowColor" from the "MyApp" section only if
  1527.  the size of the data is equal to the size of the RGB structure.
  1528.  
  1529.  HINI hini;
  1530.  ULONG cb;
  1531.  RGB rgb;
  1532.  
  1533.  PrfQueryProfileSize(hini, "MyApp", "MainWindowColor", &cb);
  1534.  if (cb==sizeof(RGB))
  1535.      PrfQueryProfileData(hini, "MyApp", "MainWindowColor", &rgb, &cb);
  1536.  
  1537.  You can also read strings by using the PrfQueryProfileString function and
  1538.  write strings by using the PrfWriteProfileString function. You can read
  1539.  integers (stored as strings) by using the PrfQueryProfileInt function.
  1540.  
  1541.  
  1542.  2.4.2.3  Identifying the Initialization Files
  1543.  
  1544.  You can retrieve the names of the MS OS/2 initialization files by using the
  1545.  PrfQueryProfile function. Although the MS OS/2 initialization files are
  1546.  usually named os2.ini and os2sys.ini, a user can use other files when
  1547.  starting the system.
  1548.  
  1549.  The following example retrieves the names of the MS OS/2 initialization
  1550.  files and copies the names of the initialization files to the arrays
  1551.  szUserName and szSysName. Once you know the names of the MS OS/2
  1552.  initialization files, you can use that name to open the files and read
  1553.  settings.
  1554.  
  1555.  char szUserName[80];
  1556.  char szSysName[80];
  1557.  PRFPROFILE prfpro = { 80, (PSZ) szUserName, 80, (PSZ) szSysName };
  1558.  
  1559.  PrfQueryProfile(hini, &prfpro);
  1560.  
  1561.  
  1562.  
  1563.  
  1564.  You can change the MS OS/2 initialization files to files of your choice by
  1565.  using the PrfReset function. This function takes the names of two
  1566.  initialization files and uses them as replacements for the os2.ini and
  1567.  os2sys.ini files. The system is then reset using the settings in the new
  1568.  files.
  1569.  
  1570.  
  1571.  2.4.2.4  Creating Groups and Program Lists
  1572.  
  1573.  You can create a group and a list of programs by using the PrfCreateGroup
  1574.  and PrfAddProgram functions. A group is a window, managed by Desktop
  1575.  Manager, that contains a list of programs. The user can start a program in
  1576.  the list by selecting the program title or double-clicking the title using
  1577.  the mouse.
  1578.  
  1579.  The following example creates a new group, named "My Application," and adds
  1580.  one program to it:
  1581.  
  1582.  HPROGRAM hGroup;
  1583.  HPROGRAM hProg;
  1584.  PROGDETAILS progde;
  1585.  
  1586.  progde.Length =          sizeof(PROGDETAILS);
  1587.  progde.progt.progc =     PROG_PM;                /* Prof. Mngr. prog. */
  1588.  progde.progt.fbVisible = SHE_VISIBLE;            /* visible           */
  1589.  progde.pszTitle =        "My Application";       /* program title     */
  1590.  progde.pszExecutable =   "c:\\os2\\myapp.exe";   /* path to exe file  */
  1591.  progde.pszStartupDir =   "c:\\os2";              /* work directory    */
  1592.  progde.pszIcon =          "";                    /* empty if not used */
  1593.  progde.pszEnvironment =   "";
  1594.  progde.pszParameters =    "";
  1595.  progde.swpInitial.fs =    0;
  1596.  progde.swpInitial.cx =    0;
  1597.  progde.swpInitial.cy =    0;
  1598.  progde.swpInitial.x =     0;
  1599.  progde.swpInitial.y =     0;
  1600.  progde.swpInitial.hwndInsertBehind = NULL;
  1601.  progde.swpInitial.hwnd =  NULL;
  1602.  
  1603.  hGroup = PrfCreateGroup(HINI_USER, "My Application", SHE_VISIBLE);
  1604.  hProg = PrfAddProgram(HINI_USER, &progde, hGroup);
  1605.  
  1606.  
  1607.  
  1608.  
  1609.  
  1610.  2.4.3  Summary
  1611.  
  1612.  Profile Manager functions open and modify the MS OS/2 initialization files.
  1613.  Note that these functions are new with MS OS/2 version 1.2 and replace the
  1614.  Win initialization-file functions in previous versions of MS OS/2.
  1615.  
  1616.  PrfAddProgram  Adds a program title to Desktop Manager.
  1617.  
  1618.  PrfChangeProgram  Replaces information in the program list.
  1619.  
  1620.  PrfCloseProfile  Closes a profile file.
  1621.  
  1622.  PrfCreateGroup  Creates a new program group in a program list.
  1623.  
  1624.  PrfDestroyGroup  Removes a group from Desktop Manager.
  1625.  
  1626.  PrfOpenProfile  Opens a profile file.
  1627.  
  1628.  PrfQueryDefinition  Retrieves program information.
  1629.  
  1630.  PrfQueryProfile  Retrieves profile filenames.
  1631.  
  1632.  PrfQueryProfileData  Retrieves information from the profile file.
  1633.  
  1634.  PrfQueryProfileInt  Retrieves an integer from the profile file.
  1635.  
  1636.  PrfQueryProfileSize  Retrieves the size of data stored at a specified
  1637.  location in the profile file.
  1638.  
  1639.  PrfQueryProfileString  Retrieves a string from the profile file.
  1640.  
  1641.  PrfQueryProgramCategory  Retrieves the program type.
  1642.  
  1643.  PrfQueryProgramHandle  Retrieves program handles that match the name of a
  1644.  specified executable file.
  1645.  
  1646.  PrfQueryProgramTitles  Retrieves information about programs in a group.
  1647.  
  1648.  PrfRemoveProgram  Removes a program from Desktop Manager.
  1649.  
  1650.  PrfReset  Resets Presentation Manager.
  1651.  
  1652.  PrfWriteProfileData  Places binary data in the profile file.
  1653.  
  1654.  PrfWriteProfileString  Places a string in the profile file.
  1655.  
  1656.  
  1657.  2.5  Help Manager
  1658.  
  1659.  This section describes how to use Help Manager in MS OS/2 to display help
  1660.  information about your application to the user. Before reading this section,
  1661.  you should be familiar with the Help Manager user interface, messages and
  1662.  message queues, and menus.
  1663.  
  1664.  Help Manager functions and messages replace the help messages and help hook
  1665.  described in the Microsoft Operating System/2 Programmer's Reference, Volume
  1666.  1.
  1667.  
  1668.  
  1669.  2.5.1  About Help Manager
  1670.  
  1671.  You use Help Manager to create help panels and to manage user requests for
  1672.  help. A help panel is one or more lines of text that describe some feature
  1673.  of the application. The help panels for an application are stored in
  1674.  compressed format in a help library. The help library is a separate disk
  1675.  file rather than a resource within in the application's executable file.
  1676.  This makes it easy to update a help library or to replace it with
  1677.  international versions of help.
  1678.  
  1679.  The user requests help in one of three ways: by pressing the F1 key, by
  1680.  using the Help menu, or by clicking the Help button in a dialog box or
  1681.  message box. The application must provide the Help menu and Help buttons in
  1682.  the application, and it must identify a specific help panel for each command
  1683.  or button. When the user requests help, Help Manager displays a help window
  1684.  alongside the application window and fills the help window with the text of
  1685.  the corresponding help panel. The user can either view additional help
  1686.  panels in the help window by using the commands in this help window or
  1687.  dismiss the help window and return to the application.
  1688.  
  1689.  While the user views help panels, Help Manager processes all user input,
  1690.  notifying the application of actions carried out for or requested by the
  1691.  user. For example, the user can search for, print, or copy help panels by
  1692.  using commands from menus in the help window. Help Manager carries out these
  1693.  actions without assistance from the application. In some cases, Help Manager
  1694.  sends a message to the application window so that the application can
  1695.  determine what additional action to take. For example, if the user input
  1696.  results in an error, Help Manager sends an HM_ERROR message to the
  1697.  application.
  1698.  
  1699.  Help Manager supports hypertext fields─words or phrases in one help panel
  1700.  that refer to other help panels. The user directs Help Manager to display
  1701.  the other help panels by choosing the hypertext field (using either the
  1702.  mouse or the keyboard). Hypertext fields can also direct Help Manager to
  1703.  display help panels from other help libraries and even to start other
  1704.  applications. For example, a hypertext field can direct Help Manager to send
  1705.  a message to the application window to start the application tutorial.
  1706.  
  1707.  You create help libraries by using the Information Presentation Facility
  1708.  Compiler (IPFC). This compiler produces the compressed help library from the
  1709.  text files that contain your help text. The help text consists of actual
  1710.  text and embedded information tags. The information tags direct the compiler
  1711.  to carry out specific actions, such as setting the help-panel name and
  1712.  identifier, setting the font and/or color of the text, displaying text in
  1713.  special formats such as lists or tables, adding a bitmap to the panel, and
  1714.  including help text from another file. For more information about the
  1715.  Information Presentation Facility Compiler, you must use QuickHelp, the
  1716.  display application for Microsoft documentation databases, described in
  1717.  Microsoft Operating System/2 Getting Started. The Information Presentation
  1718.  Facility Compiler is available only in the Microsoft OS/2 Presentation
  1719.  Manager Toolkit versions 1.2 and later.
  1720.  
  1721.  
  1722.  2.5.2  Using Help Manager in Applications
  1723.  
  1724.  When using an application, a user should have three ways to access help: by
  1725.  pressing the F1 key, by choosing commands from the Help menu, and by
  1726.  clicking a Help button. Help Manager provides support for all three methods.
  1727.  The following sections explain how to enable this support for your
  1728.  application.
  1729.  
  1730.  
  1731.  2.5.2.1  Creating a Help Instance
  1732.  
  1733.  An application can create an instance of Help Manager by using the
  1734.  WinCreateHelpInstance function. This function installs a help hook,
  1735.  initializes Help Manager for help processing, and returns a help-instance
  1736.  window handle. The application uses the help-instance window handle to
  1737.  direct Help Manager to carry out requests for help.
  1738.  
  1739.  To create a help instance, the application first fills a HELPINIT structure
  1740.  with information about the help table, the title of the help window, and the
  1741.  help library for the help instance. In the following example, the hinit
  1742.  parameter is the HELPINIT structure. The hab parameter is the anchor-block
  1743.  handle of the application, returned by the WinInitialize function.
  1744.  
  1745.  HAB hab;
  1746.  HWND hwndHelp;
  1747.  HELPINIT hinit = {
  1748.      sizeof(HELPINIT),                /* count of bytes in structure    */
  1749.      0L,                              /* return value from Help Manager */
  1750.      NULL,                            /* pointer to tutorial name       */
  1751.      MAKELONG(MY_RESOURCES, 0xFFFF)   /* resource ID for help table     */
  1752.      NULL,                            /* handle to help table           */
  1753.      NULL,                            /* handle to replacement menu     */
  1754.      0,                               /* replacement accelerator ID     */
  1755.      0,                               /* replacement menu ID            */
  1756.      "My Help!",                      /* help-window title              */
  1757.      CMIC_HIDE_PANEL_ID,              /* display help title only        */
  1758.      "c:\\os2\\help\\myhelp.hlp"      /* path to help library           */
  1759.      };
  1760.  
  1761.  
  1762.  hwndHelp = WinCreateHelpInstance(hab, &hinit);
  1763.  
  1764.  
  1765.  
  1766.  
  1767.  The application must associate the help instance with a window by using the
  1768.  WinAssociateHelpInstance function. This association tells Help Manager which
  1769.  help instance to use when the user requests help in the window or in any of
  1770.  that window's child or owned windows. A help instance can be associated with
  1771.  any frame window (that is, any window created with the WC_FRAME class). The
  1772.  application always can retrieve the handle of the associated window for a
  1773.  help instance by using the WinQueryHelpInstance function.
  1774.  
  1775.  The user requests help by pressing the F1 key, by choosing a command from
  1776.  the Help menu, or by clicking a Help button. These actions cause MS OS/2 to
  1777.  send a WM_HELP message to an application window procedure. To enable Help
  1778.  Manager to process the message and display help, the window procedure should
  1779.  pass the WM_HELP message to the WinDefWindowProc or WinDefDlgProc function.
  1780.  Although most window procedures immediately pass the WM_HELP message to the
  1781.  WinDefWindowProc or WinDefDlgProc function, a window procedure can carry out
  1782.  some processing of the WM_HELP message before it passes the message, as
  1783.  shown in the following example. In all cases, however, the window procedure
  1784.  must return the value returned by WinDefWindowProc or WinDefDlgProc.
  1785.  
  1786.  case WM_HELP:
  1787.      /* Preprocess the message here. */
  1788.      return (WinDefWindowProc(hwnd, msg, mp1, mp2));
  1789.  
  1790.  
  1791.  
  1792.  
  1793.  
  1794.  2.5.2.2  Creating a Help Table
  1795.  
  1796.  A help table is a list of window identifiers and corresponding help-panel
  1797.  identifiers. For each help request, Help Manager uses a help table to
  1798.  translate into a panel identifier the window identifier given with the
  1799.  request for help. Every help instance must have a help table.
  1800.  
  1801.  The application must create the help table and associate the help table with
  1802.  the help instance. An application creates a help table by defining it in a
  1803.  resource script file or by initializing a HELPTABLE structure. Most
  1804.  applications define the help table in the resource script file, using the
  1805.  HELPTABLE and HELPSUBTABLE statements as follows:
  1806.  
  1807.  HELPSUBTABLE MY_MAIN_WINDOW_HELP
  1808.  BEGIN
  1809.      HELPSUBITEM  IDM_HELPFORHELP,  IDH_FORHELP
  1810.      HELPSUBITEM  IDM_EXTENDEDHELP, IDH_FOREXTENDED
  1811.      HELPSUBITEM  IDM_KEYSHELP,     IDH_KEYS
  1812.      HELPSUBITEM  IDM_HELPINDEX,    IDH_INDEX
  1813.      HELPSUBITEM  IDM_ABOUT,        IDH_ABOUT
  1814.  END
  1815.  
  1816.  HELPSUBTABLE MY_DIALOG_HELP
  1817.  BEGIN
  1818.      HELPSUBITEM  MY_DIALOG,      IDH_DLG_EXTENDED
  1819.      HELPSUBITEM  MY_DIALOG_EDIT, IDH_DLG_EDIT
  1820.  END
  1821.  
  1822.  HELPTABLE MY_MAIN_WINDOW
  1823.  BEGIN
  1824.      HELPITEM MY_MAIN_WINDOW, MY_MAIN_WINDOW_HELP, IDH_EXTENDED
  1825.      HELPITEM MY_DIALOG,      MY_DIALOG_HELP,      IDH_DLG_EXTENDED
  1826.  END
  1827.  
  1828.  
  1829.  
  1830.  
  1831.  In the preceding example, the HELPTABLE statement defines the help table. It
  1832.  specifies help for two windows: the main window and a dialog window. (The
  1833.  MY_MAIN_WINDOW and MY_DIALOG constants, defined elsewhere, must be unique
  1834.  and must be equal to the window identifiers for these given windows.)
  1835.  
  1836.  The HELPITEM statements within the HELPTABLE statement identify the main and
  1837.  dialog windows and the help subtables that apply to them. A help subtable
  1838.  specifies the help-panel identifier that corresponds to a window identifier.
  1839.  The HELPITEM statements also specify the help-panel identifier for the
  1840.  extended help associated with each window. For example, the dialog window
  1841.  has the help subtable MY_DIALOG_HELP and the IDH_DLG_EXTENDED extended help
  1842.  panel (the constants MY_DIALOG_HELP and IDH_DLG_EXTENDED must be defined
  1843.  elsewhere).
  1844.  
  1845.  The HELPSUBTABLE statements define the window identifiers and corresponding
  1846.  help-panel identifiers for each child window of the specified main or dialog
  1847.  window.
  1848.  
  1849.  After receiving a help request, Help Manager determines which window is
  1850.  active and uses the identifier of the active window to select a help
  1851.  subtable. Help Manager then determines the identifier of the window that has
  1852.  the input focus (if any) and uses the identifier of the focus window with
  1853.  the selected help subtable to identify the help panel. After Help Manager
  1854.  identifies the help panel, it displays the help panel in the help window.
  1855.  Help Manager positions the help window next to the "relative" window (the
  1856.  relative window is the window next to which the system displays the help
  1857.  window). The relative window is usually the active window, but it can be set
  1858.  to another window by using the HM_SET_ACTIVE_WINDOW message.
  1859.  
  1860.  
  1861.  2.5.2.3  Creating a Help Library
  1862.  
  1863.  You create a help library by using a text editor to create a help text file
  1864.  and then compiling the help text file with the Information Presentation
  1865.  Facility Compiler (IPFC). The help library must contain one or more help
  1866.  panels, each with a unique panel identifier or name. In the help text file,
  1867.  each help panel must start with the :h1 tag. The help text file itself must
  1868.  start with the :userdoc. tag and end with the :euserdoc. tag. The following
  1869.  help text file contains two help panels:
  1870.  
  1871.      :userdoc.
  1872.      :h1 res=1.Extended Help
  1873.      Display this help when the user requests extended help.
  1874.      :h1 res=2.Other Help.
  1875.      Display this help when the user requests any other help.
  1876.  
  1877.      :euserdoc.
  1878.  
  1879.  
  1880.  
  1881.  
  1882.  The res= option with the :h1 tag identifies the panel identifier for the
  1883.  help panel. The text immediately following the :h1 tag specifies the title
  1884.  of the panel. For example, "Extended Help" is the title of the first panel,
  1885.  and "Other Help" is the title of the second. All subsequent text, up to the
  1886.  next :h1 tag, belongs to that help panel.
  1887.  
  1888.  
  1889.  2.5.2.4  Using the F1 Key
  1890.  
  1891.  The F1 key is the system Help key. Help Manager automatically enables this
  1892.  key for a window whenever an application creates a help instance and
  1893.  associates it with the frame window. The user can display help for specific
  1894.  items in the window, such as menu commands, by selecting the item and
  1895.  pressing the F1 key. Whenever the user presses the F1 key, Help Manager
  1896.  retrieves the identifier of the selected item and uses the identifier to
  1897.  locate the corresponding help-panel identifier. If Help Manager finds a
  1898.  help-panel identifier, it displays that help panel. Otherwise, it displays
  1899.  the extended help panel.
  1900.  
  1901.  Although Help Manager carries out all processing for the F1 key, the
  1902.  application must provide appropriate help-table entries for each item that
  1903.  can be selected. If the active window is not directly associated with a help
  1904.  instance, Help Manager checks the window's parent and owner windows until it
  1905.  finds an associated help instance. It first checks the parent window, the
  1906.  parent window of the parent window, and so on, until it finds a window that
  1907.  has an associated help instance. Help Manager checks the owner window only
  1908.  if the parent-window check ended at the desktop and no help instance was
  1909.  found.
  1910.  
  1911.  
  1912.  2.5.2.5  Using the Help Menu
  1913.  
  1914.  The Help menu lets the user view general help for an application. The menu
  1915.  appears as the last (rightmost) menu in the menu bar and contains the
  1916.  following commands:
  1917.  
  1918.  Command                           Description
  1919.  ────────────────────────────────────────────────────────────────────────────
  1920.  
  1921.  Help for Help                     Displays general information about help
  1922.                                    and how to access help.
  1923.  
  1924.  Extended Help                     Displays information about the
  1925.                                    application window. This help
  1926.                                    information can explain the fields in
  1927.                                    the window, the window's purpose, and
  1928.                                    how the user should interact with the
  1929.                                    window.
  1930.  
  1931.  Keys Help                         Displays a list of the function keys
  1932.                                    used by the application.
  1933.  
  1934.  Help index                        Displays an alphabetic list of all the
  1935.                                    help-index entries for the application.
  1936.                                    The author of the help-text source file
  1937.                                    creates the help index by including
  1938.                                    index tags within the help file.
  1939.  
  1940.  About                             Displays copyright information for the
  1941.                                    application. The About command is used
  1942.                                    only in the Help menu for the
  1943.                                    application window.
  1944.  
  1945.  
  1946.  
  1947.  The application must create the Help menu, add it to the menu bar, and
  1948.  process the menu commands. The most convenient way to create the Help menu
  1949.  and add it to the menu bar is to place the following statements in the
  1950.  application's MENU statement in the resource script file:
  1951.  
  1952.  SUBMENU "~Help", 1
  1953.  BEGIN
  1954.      MENUITEM "~Help for Help...",    IDM_HELPFORHELP
  1955.      MENUITEM "~Extended Help...",    IDM_EXTENDEDHELP
  1956.      MENUITEM "~Keys Help...",        IDM_KEYSHELP
  1957.      MENUITEM "Help ~index...",       IDM_HELPINDEX
  1958.      MENUITEM SEPARATOR
  1959.      MENUITEM "A~bout...",            IDM_ABOUT
  1960.  END
  1961.  
  1962.  
  1963.  
  1964.  
  1965.  You can assign any values for the IDM_ constants (IDM_HELPFORHELP and
  1966.  IDM_EXTENDEDHELP, for example) as long as the values are unique within the
  1967.  menu.
  1968.  
  1969.  To process the menu commands, the window procedure for the application must
  1970.  process the WM_COMMAND message. The application receives a WM_COMMAND
  1971.  message whenever the user chooses one of the menu commands. For each
  1972.  Help-menu command, the application must send an appropriate help message to
  1973.  the help instance for the application, as shown in the following statements:
  1974.  
  1975.  
  1976.  case WM_COMMAND:
  1977.      switch (SHORT1FROMMP(mp1)) {
  1978.      case IDM_HELPFORHELP:           /* display help for help panel */
  1979.          WinSendMsg(hwndHelp, HM_DISPLAY_HELP,
  1980.                               MPFROMSHORT(IDH_HELPFORHELP),
  1981.                               MPFROMSHORT(HM_RESOURCEID));
  1982.          break;
  1983.      case IDM_EXTENDEDHELP:          /* display extended help       */
  1984.          WinSendMsg(hwndHelp, HM_EXT_HELP, 0L, 0L);
  1985.          break;
  1986.      case IDM_KEYSHELP:              /* display keys help panel     */
  1987.          WinSendMsg(hwndHelp, HM_KEYS_HELP, 0L, 0L);
  1988.          break;
  1989.      case IDM_HELPINDEX:             /* display help index          */
  1990.          WinSendMsg(hwndHelp, HM_HELP_INDEX, 0L, 0L);
  1991.          break;
  1992.      case IDM_ABOUT:                 /* create about dialog box     */
  1993.          WinDlgBox(HWND_DESKTOP, hwnd, MyAboutProc,
  1994.              NULL, MY_ABOUTBOX, NULL); break;
  1995.      }
  1996.      return (0L);
  1997.  
  1998.  
  1999.  
  2000.  
  2001.  In the preceding statements, the HM_DISPLAY_HELP message directs Help
  2002.  Manager to display the specific help panel. You can identify the panel by
  2003.  using a panel identifier or by using a panel name. In this example, the
  2004.  constant HM_RESOURCEID directs Help Manager to locate the panel by using the
  2005.  IDH_HELPFORHELP panel identifier.
  2006.  
  2007.  The HM_EXT_HELP message directs Help Manager to display extended help for
  2008.  the help instance. The panel identifier for extended help is specified in
  2009.  the help table of the help instance. When Help Manager receives HM_EXT_HELP,
  2010.  it uses the extended help-panel identifier to locate and display extended
  2011.  help.
  2012.  
  2013.  The HM_KEYS_HELP message directs Help Manager to display the help panel that
  2014.  contains a description of the application keys. Although the application
  2015.  must supply the panel identifier for keys help, the HM_KEYS_HELP message
  2016.  does not take parameters. Instead, whenever Help Manager receives this
  2017.  message, it sends the HM_QUERY_KEYS_HELP message back to the application.
  2018.  The application must return the keys-help panel identifier as shown in the
  2019.  following statements:
  2020.  
  2021.  case HM_QUERY_KEYS_HELP:
  2022.      return (IDH_KEYSHELP);
  2023.  
  2024.  
  2025.  
  2026.  
  2027.  The HM_HELP_INDEX message directs Help Manager to display the help index for
  2028.  the help instance. Because the help index has no explicit panel identifier,
  2029.  this is the only way to display the help index from the application.
  2030.  
  2031.  Although the About command is usually placed in the Help menu, Help Manager
  2032.  does not support the About command. The application can use the WinDlgBox
  2033.  function to display a dialog box that contains copyright information in
  2034.  response to the user's choosing the About command. A corresponding dialog
  2035.  template must be defined in the resource script file.
  2036.  
  2037.  
  2038.  2.5.2.6  Using Help Buttons
  2039.  
  2040.  Help buttons provide an alternative way to display contextual help for
  2041.  fields in dialog boxes. A Help button is a push button that displays help
  2042.  information when the user clicks it by using the mouse. It usually appears
  2043.  in the lower-right part of a dialog box. Clicking a Help button has the same
  2044.  effect as pressing the F1 key (that is, it displays information about the
  2045.  selected field).
  2046.  
  2047.  The application must add Help buttons to dialog boxes, but Help Manager
  2048.  carries out the processing. The most convenient way to add a Help button to
  2049.  a dialog box is to use a PUSHBUTTON statement in the dialog template in the
  2050.  resource script file. The following statements define a very simple dialog
  2051.  box with a Help button:
  2052.  
  2053.  DLGTEMPLATE MY_DIALOG
  2054.  BEGIN
  2055.      DIALOG "My Dialog!", MY_DIALOG, 0,0, 200,85,,FCF_TITLEBAR
  2056.      BEGIN
  2057.          LTEXT "Enter name:", MY_LABEL, 10,40, 60,15
  2058.          ENTRYFIELD "", MY_DIALOG_EDIT, 70,40, 120,15, ES_MARGIN
  2059.          DEFPUSHBUTTON "OK", MY_OK, 10,10, 60,15
  2060.          PUSHBUTTON "~Help", MY_HELP, 110,10, 60,15,
  2061.              BS_NOPOINTERFOCUS | BS_HELP
  2062.      END
  2063.  END
  2064.  
  2065.  
  2066.  
  2067.  
  2068.  The Help button must have the BS_HELP and BS_NOPOINTERFOCUS styles. When the
  2069.  button has the BS_HELP style, the system interprets a button click as a
  2070.  request for help. When the button has the BS_NOPOINTERFOCUS style, the input
  2071.  focus does not move from the Help button when it is clicked; this allows
  2072.  Help Manager to determine which field in the dialog box is selected.
  2073.  
  2074.  
  2075.  2.5.2.7  Destroying a Help Instance
  2076.  
  2077.  When a help instance is no longer needed, you can destroy it by using the
  2078.  WinDestroyHelpInstance function. This function closes the help-instance
  2079.  window and removes the corresponding help hook. Before destroying the help
  2080.  instance, you should disassociate the help instance from the window by using
  2081.  the WinAssociateHelpInstance function and specifying a NULL window handle.
  2082.  After a help instance is disassociated, it can be destroyed.
  2083.  
  2084.  
  2085.  2.5.2.8  Handling Errors
  2086.  
  2087.  Help Manager functions typically indicate errors by returning FALSE. If a
  2088.  function is unsuccessful, the application can use the WinGetLastError
  2089.  function to retrieve the value of the error.
  2090.  
  2091.  If the user is viewing a help panel when an error occurs, Help Manager sends
  2092.  the HM_ERROR message to the active application window to notify the
  2093.  application of the error. Help Manager does not display error messages to
  2094.  the user; the application must display its own messages.
  2095.  
  2096.  
  2097.  2.5.3  Help Hooks and Help Manager
  2098.  
  2099.  Help Manager installs a help hook when the application creates the Help
  2100.  Manager instance. This hook enables Help Manager to trap user requests for
  2101.  help. When using Help Manager for your application, it is recommended that
  2102.  you do not install your own help hooks. If you choose to do so, however, you
  2103.  must install the help hook prior to creating the help instance, because the
  2104.  Help Manager help-hook procedure always returns TRUE, preventing all
  2105.  subsequent hook procedures from being called. If you do install a help hook,
  2106.  it must return FALSE so that Help Manager can process requests for help.
  2107.  
  2108.  
  2109.  2.5.4  Summary
  2110.  
  2111.  The following MS OS/2 functions and messages work with Help Manager.
  2112.  
  2113.  
  2114.  2.5.4.1  Help Functions
  2115.  
  2116.  MS OS/2 provides the following help functions:
  2117.  
  2118.  WinAssociateHelpInstance  Associates a help instance with a given window.
  2119.  
  2120.  WinCreateHelpInstance  Creates a help instance.
  2121.  
  2122.  WinCreateHelpTable  Identifies or changes the pointer to the help table.
  2123.  
  2124.  WinDestroyHelpInstance  Destroys an instance of Help Manager.
  2125.  
  2126.  WinLoadHelpTable  Identifies or changes the handle of the module that
  2127.  contains the help-table resource and the identifier of that resource.
  2128.  
  2129.  WinQueryHelpInstance  Retrieves the handle of the help instance associated
  2130.  with the specified window.
  2131.  
  2132.  
  2133.  2.5.4.2  Messages Sent by Help Manager
  2134.  
  2135.  Help Manager sends the following messages to the application:
  2136.  
  2137.  HM_ACTIONBAR_COMMAND  Sent to the application when the user chooses a
  2138.  command from an application-supplied menu.
  2139.  
  2140.  HM_ERROR  Notifies the application of an error caused by a user action.
  2141.  
  2142.  HM_EXT_HELP_UNDEFINED  Notifies the application that an extended help panel
  2143.  is not defined for the active window.
  2144.  
  2145.  HM_HELPSUBITEM_NOT_FOUND  Sent to the application when the user requests
  2146.  help about a field and the system cannot find a related entry in the help
  2147.  subtable.
  2148.  
  2149.  HM_INFORM  Notifies the application that the user has selected a hypertext
  2150.  field in the help window. The hypertext field must have been created using
  2151.  the :inform tag.
  2152.  
  2153.  HM_QUERY_KEYS_HELP  Sent to the application when the user requests keys
  2154.  help. The application responds by returning the identifier of the requested
  2155.  keys-help panel.
  2156.  
  2157.  HM_TUTORIAL  Sent to the application when the user chooses the Tutorial
  2158.  command from a help panel. The application then calls its own tutorial
  2159.  application.
  2160.  
  2161.  
  2162.  2.5.4.3  Messages Sent to Help Manager
  2163.  
  2164.  The application sends the following messages to Help Manager:
  2165.  
  2166.  HM_CREATE_HELP_TABLE  Specifies a new help table for the help instance.
  2167.  
  2168.  HM_DISMISS_WINDOW  Directs Help Manager to close the help window associated
  2169.  with the last active window.
  2170.  
  2171.  HM_DISPLAY_HELP  Directs Help Manager to display a specific help window.
  2172.  
  2173.  HM_EXT_HELP  Directs Help Manager to display the extended help panel for the
  2174.  active application window.
  2175.  
  2176.  HM_HELP_CONTENTS  Directs Help Manager to display the table of contents for
  2177.  the open help library.
  2178.  
  2179.  HM_HELP_INDEX  Directs Help Manager to display the index for the open help
  2180.  library.
  2181.  
  2182.  HM_KEYS_HELP  Directs Help Manager to display the help panel that contains
  2183.  information about the application keys.
  2184.  
  2185.  HM_LOAD_HELP_TABLE  Directs Help Manager to replace the existing help table
  2186.  with a help-table resource.
  2187.  
  2188.  HM_REPLACE_HELP_FOR_HELP  Directs Help Manager to display the
  2189.  application-defined help panel instead of the general help panel that is
  2190.  shipped with Help Manager.
  2191.  
  2192.  HM_SET_ACTIVE_WINDOW  Directs Help Manager to change the active window.
  2193.  Subsequent help messages are sent to the new active window and appear next
  2194.  to it.
  2195.  
  2196.  HM_SET_HELP_LIBRARY_NAME  Identifies the help library to the help instance.
  2197.  
  2198.  HM_SET_HELP_WINDOW_TITLE  Sets the title text of a help window.
  2199.  
  2200.  HM_SET_SHOW_PANEL_ID  Directs Help Manager to display, hide, or toggle the
  2201.  panel identifier for each help panel displayed.
  2202.  
  2203.  
  2204.  2.6  Combination Boxes
  2205.  
  2206.  This section describes how to use combination-box controls to let the user
  2207.  choose and edit items from a list. Before reading this section, you should
  2208.  be familiar with entry-field controls, list-box controls, messages and
  2209.  message queues, and standard user-interface guidelines.
  2210.  
  2211.  Combination-box controls, also called combination boxes, are a new feature
  2212.  with MS OS/2 version 1.2. They can be used in addition to entry-field
  2213.  controls, which are described in the Microsoft Operating System/2
  2214.  Programmer's Reference, Volume 1.
  2215.  
  2216.  
  2217.  2.6.1  About Combination Boxes
  2218.  
  2219.  A combination box is two controls in one: an entry field and a list box.
  2220.  Combination boxes let the user enter data by typing in the entry field or by
  2221.  choosing from a list in the list box.
  2222.  
  2223.  A combination box automatically manages the interaction between the entry
  2224.  field and the list box. For example, when the user chooses an item in the
  2225.  list box, the combination box displays the text for that item in the entry
  2226.  field. The user can then edit the text without affecting the item in the
  2227.  list box. When the user types a letter in the entry field, the combination
  2228.  box scrolls the list box contents so that items beginning with that letter
  2229.  become visible.
  2230.  
  2231.  A combination box can have one of the following styles:
  2232.  
  2233.  Style                             Meaning
  2234.  ────────────────────────────────────────────────────────────────────────────
  2235.  
  2236.  CBS_SIMPLE                        A simple combination box. A simple
  2237.                                    combination box always displays its list
  2238.                                    box. The user can enter and edit text in
  2239.                                    the entry field or choose items from the
  2240.                                    list box.
  2241.  
  2242.  CBS_DROPDOWN                      A drop-down combination box. A simple
  2243.                                    drop-down combination box displays its
  2244.                                    list box only if the user clicks the
  2245.                                    drop-down icon at the right end of the
  2246.                                    entry field. It hides the list box when
  2247.                                    the user clicks the icon a second time.
  2248.                                    In a drop-down combination box, the user
  2249.                                    can enter and edit text in the entry
  2250.                                    field or choose items from the list box.
  2251.  
  2252.  CBS_DROPDOWNLIST                  A drop-down-list combination box is
  2253.                                    similar to the drop-down combination box,
  2254.                                    but the user can choose items only from
  2255.                                    the list box. The user cannot enter or
  2256.                                    edit text in the entry field.
  2257.  
  2258.  
  2259.  
  2260.  For combination boxes that have the CBS_DROPDOWN style or the
  2261.  CBS_DROPDOWNLIST style, an application can show the list by using the
  2262.  CBM_SHOWLIST message. An application can determine whether the list is
  2263.  already showing by using the CBM_ISLISTSHOWING message.
  2264.  
  2265.  Applications can use any of the entry-field (EM_) and list-box (LM_)
  2266.  messages with combination boxes. Entry-field messages affect the entry
  2267.  field; list-box messages affect the list box. For example, an application
  2268.  can use the message LM_INSERTITEM to insert items into the list box. For
  2269.  more information on the entry-field and list-box messages, see the Microsoft
  2270.  Operating System/2 Programmer's Reference, Volume 1 and Volume 2.
  2271.  
  2272.  A combination box sends a variety of notification messages to its parent
  2273.  window. These notification messages are similar to the notification messages
  2274.  sent by entry-field and list-box controls. For example, the combination box
  2275.  sends a CBN_EFCHANGE notification message when the user changes text in the
  2276.  entry field and sends CBN_LBSELECT when the user chooses an item in the list
  2277.  box.
  2278.  
  2279.  
  2280.  2.6.2  Using Combination Boxes
  2281.  
  2282.  You can create a combination box by using the WinCreateWindow function or by
  2283.  specifying a COMBOBOX statement in a dialog-window template in a resource
  2284.  file. When creating a combination box by using WinCreateWindow, you must
  2285.  specify the WC_COMBOBOX class, the predefined class for a combination box.
  2286.  If you do not specify a style, the default styles WS_GROUP, WS_TABSTOP, and
  2287.  WS_VISIBLE are used.
  2288.  
  2289.  
  2290.  2.6.3  Summary
  2291.  
  2292.  The following MS OS/2 messages are used with combination-box controls.
  2293.  
  2294.  
  2295.  2.6.3.1  Messages Sent to a Combination Box
  2296.  
  2297.  An application sends these messages to a combination box:
  2298.  
  2299.  CBM_HILITE  Sets drop-down button highlighting in a combination box.
  2300.  
  2301.  CBM_ISLISTSHOWING  Determines whether a list box is visible in a combination
  2302.  box.
  2303.  
  2304.  CBM_SHOWLIST  Shows or hides the list box in a combination box.
  2305.  
  2306.  
  2307.  2.6.3.2  Messages Sent by a Combination Box
  2308.  
  2309.  Messages sent from a combination box to an owner window notify the owner of
  2310.  events in the combination box, such as when the user edits text. A
  2311.  combination box sends the following message to an owner window:
  2312.  
  2313.  WM_CONTROL  Sent to the owner window of the combination box when a user
  2314.  event occurs in the combination box. This message contains one of the
  2315.  following notification control codes, specifying what event occurred.
  2316.  
  2317.  WM_CONTROL  Sent to the owner window of the combination box when a user
  2318.  event occurs in the combination box. This message contains one of the
  2319.  following notification control codes, specifying what event occurred.
  2320.  
  2321.  Code                              Description
  2322.  ────────────────────────────────────────────────────────────────────────────
  2323.  
  2324.  CBN_EFCHANGE                      Indicates that text in a combination-box
  2325.                                    entry field has changed.
  2326.  
  2327.  CBN_EFSCROLL                      Indicates that a combination-box entry
  2328.                                    field is scrolled.
  2329.  
  2330.  CBN_ENTER                         Indicates that a combination-box item is
  2331.                                    selected.
  2332.  
  2333.  CBN_LBSCROLL                      Indicates that a combination-box list is
  2334.                                    scrolled.
  2335.  
  2336.  CBN_LBSELECT                      Indicates that a combination-box list
  2337.                                    item is selected.
  2338.  
  2339.  CBN_MEMERROR                      Indicates that the combination box
  2340.                                    cannot allocate sufficient memory.
  2341.  
  2342.  CBN_SHOWLIST                      Indicates that a combination-box list
  2343.                                    has dropped down (is visible).
  2344.  
  2345.  
  2346.  
  2347.  2.7  Multiple-Line Entry Fields
  2348.  
  2349.  This section describes how to use multiple-line entry fields to let the user
  2350.  view and edit text in an application. Before reading this section, you
  2351.  should be familiar with entry-field controls, messages and message queues,
  2352.  and standard user-interface guidelines.
  2353.  
  2354.  Multiple-line entry fields are a new feature with MS OS/2 version 1.2 and
  2355.  can be used in addition to entry-field controls, which are described in the
  2356.  Microsoft Operating System/2 Programmer's Reference, Volume 1.
  2357.  
  2358.  
  2359.  2.7.1  About Multiple-Line Entry Fields
  2360.  
  2361.  A multiple-line entry field (MLE) is a sophisticated control window that
  2362.  users use to view and edit multiple lines of text. An MLE provides all the
  2363.  text-editing capabilities of a simple text editor, making these features
  2364.  readily available to applications.
  2365.  
  2366.  You can create multiple-line entry fields by using the WinCreateWindow
  2367.  function or by specifying the MLE statement in a dialog-window template in a
  2368.  resource file.
  2369.  
  2370.  
  2371.  2.7.1.1  MLE Text Editing
  2372.  
  2373.  An MLE contains one or more lines of text. Each line consists of one or more
  2374.  characters and ends with one or more characters that represent the end of
  2375.  the line. The user inserts text by typing (when the MLE has the focus). The
  2376.  application can insert text at any time by using the MLM_INSERT message and
  2377.  specifying the text as a null-terminated string. The MLE inserts the new
  2378.  text at the cursor position or replaces the selected text.
  2379.  
  2380.  The entry mode determines the action of the MLE when the user inserts text.
  2381.  The entry mode can be set to overstrike or insertion. The user sets it by
  2382.  pressing the INS key. When overstrike mode is enabled, at least one
  2383.  character is always selected. This means that the MLM_INSERT message always
  2384.  replaces at least one character. If insert mode is enabled, the MLM_INSERT
  2385.  message replaces only characters the user or the application has selected.
  2386.  Otherwise, the MLE makes room for the inserted characters by moving existing
  2387.  characters to the right at the cursor position.
  2388.  
  2389.  The cursor position, identified by a flashing caret, is always specified as
  2390.  a character offset, relative to the beginning of text. The user sets the
  2391.  cursor position by moving the flashing caret by using the mouse or the ARROW
  2392.  keys. An application can set the cursor position by using the MLM_SETSEL
  2393.  message. This message directs the MLE to move the flashing caret to a given
  2394.  character position.
  2395.  
  2396.  The MLM_SETSEL message also sets the selection. The selection is one or more
  2397.  characters of text on which the MLE carries out an operation, such as
  2398.  deleting or copying. The user selects text by pressing the SHIFT key while
  2399.  moving the cursor. An application selects text by specifying the cursor
  2400.  position and anchor point using the MLM_SETSEL message. The selection is all
  2401.  text between the cursor position and the anchor point. If the cursor
  2402.  position and anchor point are equal, there is no selection. An application
  2403.  can retrieve the cursor position and/or anchor point by using the
  2404.  MLM_QUERYSEL message.
  2405.  
  2406.  The user can delete characters, one at a time, by pressing the DEL key or
  2407.  the BKSP key. These keys delete the character to the left of the cursor. An
  2408.  application can delete one or more characters by using the MLM_DELETE
  2409.  message. This message directs the MLE to delete a specified number of
  2410.  characters, starting at the given position. This message does not change the
  2411.  cursor position. An application can delete selected text by using the
  2412.  MLM_CLEAR message.
  2413.  
  2414.  An application can reverse the previous operation by using the MLM_UNDO
  2415.  message. This message directs the MLE to restore the entry field to its
  2416.  previous state. It is a quick way to fix users' editing mistakes.
  2417.  
  2418.  But not all operations can be undone. The application can determine whether
  2419.  the previous operation can be undone by using the MLM_QUERYUNDO message.
  2420.  This message returns TRUE and an indication of the type of operation that
  2421.  can be undone. An application can prevent a subsequent MLM_UNDO message from
  2422.  changing the state of the MLE by using the MLM_RESETUNDO message.
  2423.  
  2424.  
  2425.  2.7.1.2  MLE Text Formatting
  2426.  
  2427.  An application can retrieve the number of lines of text in an MLE by using
  2428.  the MLM_QUERYLINECOUNT message. It can retrieve the number of characters in
  2429.  the MLE by using the MLM_QUERYTEXTLENGTH message. The amount of text and,
  2430.  subsequently, the number of lines to be entered in an MLE depend on the text
  2431.  limit. An application can set the text limit by using the message
  2432.  MLM_SETTEXTLIMIT and determine the current limit by using the message
  2433.  MLM_QUERYTEXTLIMIT. The user cannot set the limit. If the user types to the
  2434.  text limit, the MLE beeps and ignores subsequent characters. If the
  2435.  application attempts to add text beyond the limit, the MLE truncates the
  2436.  text.
  2437.  
  2438.  An application can control the length of each line in an MLE by enabling
  2439.  word-wrapping. When word-wrapping is enabled, the MLE automatically breaks
  2440.  any line that is longer than the MLE is wide. An application can set
  2441.  word-wrapping by using the MLM_SETWRAP message, and it can determine whether
  2442.  the MLE is wrapping text by using the MLM_QUERYWRAP message. Unless the
  2443.  style MLS_WORDWRAP is specified when the MLE is created, word-wrapping is
  2444.  initially disabled.
  2445.  
  2446.  An application can set tab stops for an MLE by using the MLM_SETTABSTOP
  2447.  message. Tab stops specify the maximum width of tab character. When the user
  2448.  or an application inserts a tab character, the MLE expands the character so
  2449.  that it fills the space between cursor position and the next tab stop. The
  2450.  message MLM_SETTABSTOP actually sets the distance (specified in pixels)
  2451.  between tab stops, and the MLE provides as many tab stops as needed, no
  2452.  matter how long the line gets. The application can retrieve the distance
  2453.  between tab stops by using the MLM_QUERYTABSTOP message.
  2454.  
  2455.  An application can use the MLM_SETFORMATRECT message to set the format
  2456.  rectangle. The format rectangle is used to set the horizontal and/or
  2457.  vertical limits for text. The MLE sends a notification message to the parent
  2458.  window of the MLE if text exceeds the limit. An application typically uses
  2459.  the format rectangle to provide its own word-wrapping or other special text
  2460.  processing. An application can retrieve the current formatting rectangle by
  2461.  using the message MLM_QUERYFORMATRECT.
  2462.  
  2463.  An application can prevent the user from entering text in the entry field by
  2464.  using the MLM_SETREADONLY message. The MLM_QUERYREADONLY message specifies
  2465.  whether the MLE is read-only. An application can also set the MLE to
  2466.  read-only by specifying the MLS_READONLY style when creating the MLE.
  2467.  
  2468.  An application can set the colors and font for an MLE by using the messages
  2469.  MLM_SETTEXTCOLOR, MLM_SETBACKCOLOR, and MLM_SETFONT. These messages affect
  2470.  all text in the MLE; an MLE cannot contain a mixture of fonts and colors. An
  2471.  application can retrieve the current values for the color and the font by
  2472.  using MLM_QUERYTEXTCOLOR, MLM_QUERYBACKCOLOR, and MLM_QUERYFONT.
  2473.  
  2474.  
  2475.  2.7.1.3  Importing and Exporting MLE Text
  2476.  
  2477.  An application can copy text to and from an MLE by importing and exporting.
  2478.  Importing using the MLM_IMPORT message copies text from a buffer to the MLE.
  2479.  Exporting using the MLM_EXPORT message copies text from the MLE to a buffer.
  2480.  The application uses the MLM_SETIMPORTEXPORT message to set the import and
  2481.  export buffers. To import, the application must fill the buffer with the
  2482.  text to copy to the MLE. To export, the MLE copies the specified text to the
  2483.  buffer.
  2484.  
  2485.  An application can import and export text in a variety of formats. The text
  2486.  format identifies which characters are used for the end-of-line characters
  2487.  and is set by using the MLM_FORMAT message. An MLE can have the following
  2488.  text formats:
  2489.  
  2490.  Type                              Format
  2491.  ────────────────────────────────────────────────────────────────────────────
  2492.  
  2493.  MLFIE_CFTEXT                      Exported lines end with a
  2494.                                    carriage-return/newline character pair
  2495.                                    (0x0D, 0x0A). Imported lines must end
  2496.                                    with a newline character, a
  2497.                                    carriage-return/newline character pair,
  2498.                                    or a newline/carriage-return character
  2499.                                    pair.
  2500.  
  2501.  MLFIE_NOTRANS                     Imported and exported lines end with a
  2502.                                    newline character (0x0A).
  2503.  
  2504.  MLFIE_WINFMT                      For exported lines, the
  2505.                                    carriage-return/newline character pair
  2506.                                    marks a hard line break (a break entered
  2507.                                    by the user), and two carriage-return
  2508.                                    characters and a newline character (0x0D,
  2509.                                    0x0D, 0x0A) mark a soft line break (a
  2510.                                    break inserted during word-wrapping, not
  2511.                                    entered by the user). For imported lines,
  2512.                                    soft line break characters are ignored.
  2513.  
  2514.  
  2515.  
  2516.  The text format can affect the number of characters in a selection. To
  2517.  ensure that the export buffer is large enough to hold exported text, an
  2518.  application can send the message MLM_QUERYFORMATLINELENGTH and the message
  2519.  MLM_QUERYFORMATTEXTLENGTH to determine the number of bytes in text to be
  2520.  exported.
  2521.  
  2522.  Each time an application inserts text in an MLE, the MLE automatically
  2523.  refreshes the display by drawing the new text. When an application copies
  2524.  large amounts of text to an MLE, refreshing can be quite time-consuming, so
  2525.  applications should disable the automatic refresh setting in such cases. An
  2526.  application can disable this setting by sending the MLM_DISABLEREFRESH
  2527.  message. After copying all the text, the application can restore the refresh
  2528.  by sending the MLM_ENABLEREFRESH message.
  2529.  
  2530.  
  2531.  2.7.1.4  MLE Cut, Copy, and Paste Operations
  2532.  
  2533.  The user can cut, copy, and paste text in an MLE by using the CTRL+DEL,
  2534.  SHIFT+DEL, and SHIFT+INS keys. An application can cut, copy, and paste text
  2535.  by using the MLM_CUT, MLM_COPY, and MLM_PASTE messages. The MLM_CUT and
  2536.  MLM_COPY messages direct the MLE to copy the selected text to the clipboard.
  2537.  MLM_CUT also deletes the text (MLM_COPY does not). The MLM_PASTE message
  2538.  directs the MLE to copy the text on the clipboard to the current position in
  2539.  the MLE, replacing any existing text with the copied text. An application
  2540.  can delete the selected text without copying it to the clipboard by using
  2541.  the MLM_CLEAR message.
  2542.  
  2543.  An application can also copy the selected text from an MLE to a buffer by
  2544.  using the MLM_QUERYSELTEXT message. This message does not affect the
  2545.  contents of the clipboard.
  2546.  
  2547.  
  2548.  2.7.1.5  MLE Search and Replace Operations
  2549.  
  2550.  An application can search for a specified string within MLE text by using
  2551.  the MLM_SEARCH message. This message directs the MLE to search for the
  2552.  string. If the string is found, the MLE returns TRUE. The cursor does not
  2553.  move to the string unless the message specifies the MLFSEARCH_SELECTMATCH
  2554.  option.
  2555.  
  2556.  An application can also use the MLM_SEARCH message to replace one string
  2557.  with another. If the MLFSEARCH_CHANGEALL option is specified, the MLE
  2558.  replaces all occurrences of the search string with the replacement string.
  2559.  Both the search string and the replacement string must be specified in an
  2560.  MLE_SEARCHDATA structure passed with the message.
  2561.  
  2562.  
  2563.  2.7.1.6  MLE Notification Codes
  2564.  
  2565.  An MLE sends notification codes to its parent window whenever certain events
  2566.  occur, for example, when the user or the application tries to insert too
  2567.  much text or when the user uses the scroll bars. The parent window uses the
  2568.  notification codes to carry out custom operations for the MLE or to respond
  2569.  to errors. Notification codes that are closely related to MLE messages are
  2570.  described here.
  2571.  
  2572.  The MLE sends the MLN_HSCROLL or MLN_VSCROLL notification codes when the
  2573.  user uses the scroll bars so the application can monitor the visible
  2574.  contents of the MLE. The application can also monitor the contents of an MLE
  2575.  by using the MLM_QUERYFIRSTCHAR message. This message identifies the
  2576.  character in the upper-left corner of the MLE (by specifying its offset).
  2577.  This represents the first MLE character that is visible to the user. An
  2578.  application can move a specified character to the upper-left corner of an
  2579.  MLE by using the MLM_SETFIRSTCHAR message as an alternative way of scrolling
  2580.  the contents of an MLE.
  2581.  
  2582.  The MLE sends an MLN_CHANGE notification code when the user changes the text
  2583.  in some way. This code is especially useful when the MLE is in a dialog box,
  2584.  because it can determine whether the dialog procedure should process the
  2585.  contents of the MLE. The MLM_QUERYCHANGED message also can determine whether
  2586.  the user has made changes. The MLM_SETCHANGED message causes the MLE to send
  2587.  a notification code, regardless of whether the user has changed anything;
  2588.  this code can also be used to hide a change made by a user.
  2589.  
  2590.  
  2591.  2.7.1.7  MLE Styles
  2592.  
  2593.  MLE styles can be specified by using the WinCreateWindow function or the MLE
  2594.  statement in a resource file. Styles can be combined by using the OR
  2595.  operator. Applications can specify a combination of the following styles for
  2596.  an MLE:
  2597.  
  2598.  Style                             Meaning
  2599.  ────────────────────────────────────────────────────────────────────────────
  2600.  
  2601.  MLS_BORDER                        Draws a border around the MLE.
  2602.  
  2603.  MLS_HSCROLL                       Adds a horizontal scroll bar to the MLE.
  2604.                                    The scroll bar is enabled when any line
  2605.                                    exceeds the width of the MLE.
  2606.  
  2607.  MLS_IGNORETAB                     Directs the MLE to ignore the TAB key.
  2608.  
  2609.  MLS_READONLY                      Prevents the MLE from accepting text
  2610.                                    from the user. This style is useful for
  2611.                                    displaying lengthy static text in
  2612.                                    windows or dialog boxes.
  2613.  
  2614.  MLS_VSCROLL                       Adds a vertical scroll bar to the MLE.
  2615.                                    The scroll bar is enabled when the
  2616.                                    number of lines exceeds the height of
  2617.                                    the MLE.
  2618.  
  2619.  MLS_WORDWRAP                      Prevents lines that are longer than the
  2620.                                    width of the MLE. The MLE automatically
  2621.                                    breaks the line at a convenient place.
  2622.  
  2623.  
  2624.  
  2625.  2.7.2  Using Multiple-Line Entry Fields
  2626.  
  2627.  You can create an MLE by using the WinCreateWindow function or by specifying
  2628.  the MLE statement in a dialog-window template in a resource file. The
  2629.  following example shows how to create an MLE by using WinCreateWindow:
  2630.  
  2631.  HWND hwndParent;   /* parent-window handle  */
  2632.  HWND hwndMLE;      /* MLE handle            */
  2633.  
  2634.  hwndMLE = WinCreateWindow(hwndParent,
  2635.                WC_MLE,
  2636.                "Test",
  2637.                MLS_BORDER | WS_VISIBLE,
  2638.                100, 100, 100, 100,
  2639.                hwndParent,
  2640.                HWND_TOP,
  2641.                2, NULL, NULL);
  2642.  
  2643.  
  2644.  
  2645.  
  2646.  An MLE has the WC_MLE window class. As with other controls created using the
  2647.  WinCreateWindow function, the WS_VISIBLE style must be set to display the
  2648.  window immediately.
  2649.  
  2650.  It is more common to create an MLE by using an MLE statement in a
  2651.  dialog-window template in a resource file, as shown in the following
  2652.  example:
  2653.  
  2654.  MLE "", 101, 110, 10, 50, 100
  2655.  
  2656.  
  2657.  
  2658.  
  2659.  The predefined class for an MLE is WC_MLE. If you do not specify a style,
  2660.  the default styles MLS_BORDER, WS_GROUP, and WS_TABSTOP are used.
  2661.  
  2662.  
  2663.  2.7.3  Summary
  2664.  
  2665.  The following MS OS/2 messages are used with multiple-line entry fields.
  2666.  
  2667.  
  2668.  2.7.3.1  Messages Sent to an MLE
  2669.  
  2670.  An application sends the following messages to an MLE:
  2671.  
  2672.  MLM_CHARFROMLINE  Returns the offset to a line.
  2673.  
  2674.  MLM_CLEAR  Clears selected text in an MLE.
  2675.  
  2676.  MLM_COPY  Copies selected text from an MLE to the clipboard.
  2677.  
  2678.  MLM_CUT  Cuts selected text from an MLE to the clipboard.
  2679.  
  2680.  MLM_DELETE  Deletes text from an MLE.
  2681.  
  2682.  MLM_DISABLEREFRESH  Disables refresh for an MLE.
  2683.  
  2684.  MLM_ENABLEREFRESH  Enables screen refresh for an MLE.
  2685.  
  2686.  MLM_EXPORT  Exports text from an MLE.
  2687.  
  2688.  MLM_FORMAT  Sets format for MLE import/export.
  2689.  
  2690.  MLM_IMPORT  Imports text into an MLE.
  2691.  
  2692.  MLM_INSERT  Inserts text into an MLE.
  2693.  
  2694.  MLM_LINEFROMCHAR  Determines the line number of an MLE character.
  2695.  
  2696.  MLM_PASTE  Copies the clipboard contents to an MLE.
  2697.  
  2698.  MLM_QUERYBACKCOLOR  Retrieves the background color of an MLE.
  2699.  
  2700.  MLM_QUERYCHANGED  Determines whether text in an MLE has changed.
  2701.  
  2702.  MLM_QUERYFIRSTCHAR  Retrieves the offset of the first visible character.
  2703.  
  2704.  MLM_QUERYFONT  Retrieves current MLE font information.
  2705.  
  2706.  MLM_QUERYFORMATLINELENGTH  Retrieves the formatted MLE line length.
  2707.  
  2708.  MLM_QUERYFORMATRECT  Retrieves the dimensions and mode of an MLE.
  2709.  
  2710.  MLM_QUERYFORMATTEXTLENGTH  Retrieves the length of formatted MLE text.
  2711.  
  2712.  MLM_QUERYIMPORTEXPORT  Retrieves values for the import/export buffer.
  2713.  
  2714.  MLM_QUERYLINECOUNT  Retrieves the number of lines in an MLE.
  2715.  
  2716.  MLM_QUERYLINELENGTH  Retrieves the length of an MLE line.
  2717.  
  2718.  MLM_QUERYREADONLY  Determines the MLE read-only mode.
  2719.  
  2720.  MLM_QUERYSEL  Retrieves the selection position in an MLE.
  2721.  
  2722.  MLM_QUERYSELTEXT  Retrieves selected text from an MLE.
  2723.  
  2724.  MLM_QUERYTABSTOP  Retrieves the size of an MLE tab-stop.
  2725.  
  2726.  MLM_QUERYTEXTCOLOR  Retrieves MLE text-color information.
  2727.  
  2728.  MLM_QUERYTEXTLENGTH  Retrieves the length of MLE text.
  2729.  
  2730.  MLM_QUERYTEXTLIMIT  Retrieves the text limit of an MLE.
  2731.  
  2732.  MLM_QUERYUNDO  Determines whether an MLE can undo an operation.
  2733.  
  2734.  MLM_QUERYWRAP  Retrieves the state of word-wrap in an MLE.
  2735.  
  2736.  MLM_RESETUNDO  Resets (clears) the MLE undo flag.
  2737.  
  2738.  MLM_SEARCH  Searches an MLE.
  2739.  
  2740.  MLM_SETBACKCOLOR  Sets the background color of an MLE.
  2741.  
  2742.  MLM_SETCHANGED  Sets the MLE changed flag.
  2743.  
  2744.  MLM_SETFIRSTCHAR  Sets the first visible character.
  2745.  
  2746.  MLM_SETFONT  Sets MLE font information.
  2747.  
  2748.  MLM_SETFORMATRECT  Sets the format rectangle and mode of an MLE.
  2749.  
  2750.  MLM_SETIMPORTEXPORT  Sets the MLE import/export buffer.
  2751.  
  2752.  MLM_SETREADONLY  Sets/clears the MLE read-only state.
  2753.  
  2754.  MLM_SETSEL  Selects text within an MLE.
  2755.  
  2756.  MLM_SETTABSTOP  Sets the size of an MLE tab-stop.
  2757.  
  2758.  MLM_SETTEXTCOLOR  Sets the text color of an MLE.
  2759.  
  2760.  MLM_SETTEXTLIMIT  Sets the text limit for an MLE.
  2761.  
  2762.  MLM_SETWRAP  Sets/resets MLE word-wrap.
  2763.  
  2764.  MLM_UNDO  Undoes an MLE operation.
  2765.  
  2766.  
  2767.  2.7.3.2  Messages Sent by an MLE
  2768.  
  2769.  Messages sent from an MLE to an owner window notify the owner of events in
  2770.  the MLE, such as when the user edits text. An MLE sends the following
  2771.  message to an owner window:
  2772.  
  2773.  WM_CONTROL  Sent to the owner window of the MLE when a user event occurs in
  2774.  the MLE. This message contains one of the following notification control
  2775.  codes, specifying what event occurred.
  2776.  
  2777.  Code                              Description
  2778.  ────────────────────────────────────────────────────────────────────────────
  2779.  
  2780.  MLN_CHANGE                        Indicates that text in an MLE has
  2781.                                    changed.
  2782.  
  2783.  MLN_CLPBDFAIL                     Indicates that a clipboard operation
  2784.                                    failed.
  2785.  
  2786.  MLN_HSCROLL                       Indicates a horizontal MLE scroll event.
  2787.  
  2788.  MLN_KILLFOCUS                     Indicates that an MLE has lost the input
  2789.                                    focus.
  2790.  
  2791.  MLN_MARGIN                        Indicates that the mouse has moved over
  2792.                                    an MLE margin.
  2793.  
  2794.  MLN_MEMERROR                      Indicates that insufficient memory is
  2795.                                    available for an MLE.
  2796.  
  2797.  MLN_OVERFLOW                      Indicates that the MLE operation caused
  2798.                                    an overflow.
  2799.  
  2800.  MLN_PIXHORZOVERFLOW               Indicates an MLE horizontal overflow.
  2801.  
  2802.  MLN_PIXVERTOVERFLOW               Indicates an MLE vertical overflow.
  2803.  
  2804.  MLN_SEARCHPAUSE                   Determines the status of a search
  2805.                                    initiated by an MLM_SEARCH message.
  2806.  
  2807.  MLN_SETFOCUS                      Indicates that the MLE receives the
  2808.                                    input focus.
  2809.  
  2810.  MLN_TEXTOVERFLOW                  Indicates an MLE text-limit overflow.
  2811.  
  2812.  MLN_UNDOOVERFLOW                  Indicates that a text change cannot be
  2813.                                    undone.
  2814.  
  2815.  MLN_VSCROLL                       Indicates an MLE vertical scroll event.
  2816.  
  2817.  
  2818.  
  2819.  2.8  Printing
  2820.  
  2821.  This section describes how to print graphics and text to printers and
  2822.  plotters. You should also be familiar with the following topics:
  2823.  
  2824.    ■   Standard user-interface guidelines
  2825.  
  2826.    ■   Device contexts and presentation spaces
  2827.  
  2828.    ■   Metafiles
  2829.  
  2830.    ■   Coordinate spaces and transformations
  2831.  
  2832.    ■   Graphics programming interface (GPI)
  2833.  
  2834.  
  2835.  
  2836.  
  2837.  2.8.1  About Printing
  2838.  
  2839.  The way an MS OS/2 application prints text and graphics is similar to the
  2840.  way it displays text and graphics on the screen. In both cases, the
  2841.  application uses the same Gpi functions and can isolate the task of creating
  2842.  graphics from the task of sending them to an output device. For example, a
  2843.  word processor can display text in a window by calling Gpi character and
  2844.  string-drawing functions. When the user wants to print the text, the
  2845.  application can use the same Gpi functions; the only difference is that the
  2846.  output device is a printer instead of the screen. Printing can be thought of
  2847.  as drawing in a window the size of a sheet of paper.
  2848.  
  2849.  
  2850.  2.8.1.1  The Print Queue and the Spooler
  2851.  
  2852.  An application may share a printer with other applications in the system or
  2853.  with applications running on other systems in a network. When an application
  2854.  sends output to a printer, it should be able to continue with other
  2855.  processing while the print job is being completed. When several applications
  2856.  request print jobs at the same time, the system should handle the print jobs
  2857.  without forcing any of the applications to resend the jobs or wait for the
  2858.  jobs to be completed. These tasks are handled in MS OS/2 by Print Manager,
  2859.  the spooler, and the queue processor.
  2860.  
  2861.  Printer Installer (pmprinst.exe) is a Presentation Manager utility that
  2862.  installs a printer device driver and associates the driver with a queue.
  2863.  Printer Installer provides a simpler user interface than did the previous
  2864.  method of setting up the printing environment, which required the user to
  2865.  work with Control Panel and Print Manager.
  2866.  
  2867.  Print Manager (pmspool.exe) is a Presentation Manager utility that allows
  2868.  the user to view print queues, printer configurations, and queued print
  2869.  jobs. The user can also use Print Manager to cancel print jobs, change
  2870.  printer and queue configurations, and change the default printer and queue
  2871.  for Presentation Manager applications. (The user typically sets the default
  2872.  printer and queue by using Printer Installer, however.) Print Manager works
  2873.  with the spooler (pmspl.dll) to coordinate print jobs as they wait to be
  2874.  processed by the queue processor (pmprint.qpr). In MS OS/2 versions 1.21 and
  2875.  later, the spooler and Print Manager are always active.
  2876.  
  2877.  Most print jobs are in the form of metafiles when the spooler receives them.
  2878.  The queue processor (also called the queue driver or print processor)
  2879.  translates the contents of the metafile into printer-specific commands and
  2880.  sends these commands to the printer. (In other words, the queue processor
  2881.  "plays" the metafile on the device context of a printer driver.) For more
  2882.  information about metafiles, see the Microsoft Operating System/2
  2883.  Programmer's Reference, Volume 1.
  2884.  
  2885.  The queue and printer names and their associated device drivers are stored
  2886.  in the os2sys.ini file (os2.ini for MS OS/2 version 1.1). The user defaults
  2887.  are stored in the os2.ini file.
  2888.  
  2889.  Although most users will use Printer Installer (pmprinst.exe) to
  2890.  simultaneously set up a printer and an associated queue, a user could still
  2891.  use Control Panel and Print Manager to set up a printer without setting up a
  2892.  queue. Such a printer is called a direct printer, because print jobs are
  2893.  sent directly from the printer device driver to the physical port without
  2894.  going through the spooler or queue processor. Some printer device drivers
  2895.  (for example, pscript.drv) work with ASCII text instead of binary
  2896.  information; these drivers can use direct printing to send output directly
  2897.  to a file. Only one application at a time can print to a direct printer. The
  2898.  application does not need to determine whether its print jobs are going to
  2899.  the spooler or to a direct printer; the only difference if the user has set
  2900.  up a direct printer is that, before continuing with other processing, an
  2901.  application may have to wait for printing to finish.
  2902.  
  2903.  
  2904.  2.8.1.2  Printer Selection
  2905.  
  2906.  Before an application prints a document, it should determine what printers
  2907.  are available on the system and display their names to the user, so that the
  2908.  user can select which printer to use. If the application has previously
  2909.  stored the preferred printer device driver for a document as one of the
  2910.  document's "job properties," the printer that matches the specified driver
  2911.  and model should be given as the default choice. Otherwise, the application
  2912.  should give the system default printer as the default selection. The first
  2913.  task in printing is to determine whether any of the printers on the system
  2914.  match the job properties that may have been stored with the document.
  2915.  
  2916.  Job Properties
  2917.  
  2918.  Job properties describe characteristics of a print job that can be modified
  2919.  on a document-by-document basis─for example, paper orientation (portrait or
  2920.  landscape), print quantity, and paper form. After an application retrieves
  2921.  job properties, either from the device driver or from extended attributes
  2922.  stored with the document to be printed, it should allow the user to modify
  2923.  those job properties before beginning the print job. If the user chooses job
  2924.  properties that are different from the system default, the application
  2925.  should store the new job properties with the document as extended
  2926.  attributes. For information on storing and retrieving extended attributes,
  2927.  see Section 2.3.3.
  2928.  
  2929.  Data Retrieval from Initialization Files
  2930.  
  2931.  The initialization files, os2sys.ini and os2.ini, contain information in
  2932.  binary form about the configuration of the system, including information
  2933.  about the printers that the system supports. An application can use the
  2934.  PrfQueryProfileString function to retrieve information from these files.
  2935.  (PrfQueryProfileString works only in MS OS/2 versions 1.2 and later. If an
  2936.  application requires compatibility with earlier versions of MS OS/2, it
  2937.  should use the WinQueryProfileString function.) If job properties were
  2938.  stored with a document, an application can call the PrfQueryProfileString
  2939.  function until it finds a match between the job properties and the available
  2940.  printers. If the application cannot obtain an exact match between the job
  2941.  properties and the capabilities of available printers, it should use the
  2942.  default queue and printer that the user has defined. The system stores the
  2943.  system default queue and printer device driver in the os2.ini file; the
  2944.  default settings for each queue and printer supported by the system are in
  2945.  the os2sys.ini file.
  2946.  
  2947.  An application can use PrfQueryProfileString to retrieve many different
  2948.  kinds of information from the os2.ini and os2sys.ini files, by specifying
  2949.  which file to query in the first parameter and specifying an application
  2950.  name and a keyname in the second and third parameters, respectively. (An
  2951.  application can also use the DevQueryDeviceNames function to retrieve
  2952.  information about a particular printer device driver, although it will still
  2953.  need to use PrfQueryProfileString to retrieve the name of the device
  2954.  driver.)
  2955.  
  2956.  To retrieve the system default printer device driver or queue from os2.ini,
  2957.  the application specifies HINI_USERPROFILE as the first parameter of
  2958.  PrfQueryProfileString, PM_SPOOLER for the application name, and either
  2959.  PRINTER or QUEUE for the keyname.
  2960.  
  2961.  To retrieve data from os2sys.ini, the application specifies the constant
  2962.  HINI_SYSTEMPROFILE as the first parameter of PrfQueryProfileString. If the
  2963.  application needs information about the printer, it supplies the printer
  2964.  name as the keyname. The following list shows the application names that an
  2965.  application can use when querying printer data from the os2sys.ini file and
  2966.  the format of the data the function returns:
  2967.  
  2968.  Application name                  Format
  2969.  ────────────────────────────────────────────────────────────────────────────
  2970.  
  2971.  PM_SPOOLER_PRINTER                port;driver(s);queue(s);printer parms;
  2972.  
  2973.  PM_SPOOLER_PRINTER_DESCR          queue descr;
  2974.  
  2975.  
  2976.  
  2977.  If the application requires information about the queue, it supplies the
  2978.  queue name as the keyname. The following list shows the application names
  2979.  that an application can use when querying queue data from the os2sys.ini
  2980.  file and the format of the data the function returns:
  2981.  
  2982.  Application name                  Format
  2983.  ────────────────────────────────────────────────────────────────────────────
  2984.  
  2985.  PM_SPOOLER_QUEUE                  processor;queue parms;queue net parms;
  2986.  
  2987.  PM_SPOOLER_QUEUE_DESCR            queue descr;
  2988.  
  2989.  PM_SPOOLER_QUEUE_DD               driver;
  2990.  
  2991.  PM_SPOOLER_QUEUE_DDDATA           driver data
  2992.  
  2993.  
  2994.  
  2995.  Notice that the driver data that is returned when an application specifies
  2996.  the PM_SPOOLER_QUEUE_DDDATA constant is not followed by a semicolon. If an
  2997.  application uses this application name in a call to the
  2998.  PrfQueryProfileString function, it must parse the driver data carefully.
  2999.  
  3000.  If an application specifies PM_SPOOLER_PRINTER as the application name, the
  3001.  string returned by PrfQueryProfileString may contain more information than
  3002.  the application needs. If there is more than one printer device driver or
  3003.  queue associated with a port, all of the driver and queue names are returned
  3004.  in the string. (When there is more than one driver or queue, the default
  3005.  driver or queue is listed first.) Similarly, if model information is
  3006.  associated with a printer device driver, the driver name is followed by a
  3007.  period and the model information follows the period. The string returned by
  3008.  a call to PrfQueryProfileString that specified PM_SPOOLER_PRINTER could look
  3009.  like the following:
  3010.  
  3011.  LPT1;EPSON.24-PIN 80 COL,PSCRIPT;LPT1Q,QUEUE2;;
  3012.  
  3013.  
  3014.  
  3015.  
  3016.  In this case, port LPT1 is associated with two printer drivers and two
  3017.  queues. EPSON is the default driver and LPT1Q is the default queue. The
  3018.  epson driver is followed by information about the printer model.
  3019.  
  3020.  When an application specifies PM_SPOOLER_QUEUE_DD, model information, if
  3021.  any, follows the driver name as shown in the preceding example.
  3022.  
  3023.  An application should always check for a comma (,) to make sure only one
  3024.  name has been returned. If the application needs only the driver name, and
  3025.  not model information, it should parse the driver name and strip off text
  3026.  beginning at the period.
  3027.  
  3028.  
  3029.  2.8.1.3  Setting Job Properties
  3030.  
  3031.  When an application has determined which printer driver to use, it can use
  3032.  the default setting of the driver as the job properties or it can set the
  3033.  job properties based on information the user stored with the document. In
  3034.  either case, it can call the DevPostDeviceModes function to allow the user
  3035.  to customize the print job.
  3036.  
  3037.  The DevPostDeviceModes function causes the printer device driver to display
  3038.  either a dialog box that allows the user to set job properties, or two
  3039.  dialog boxes, one for job properties and the other for printer properties.
  3040.  (Job properties apply only to the current print job; printer properties
  3041.  change the default characteristics of the printer device driver. An
  3042.  application should not change the system default printer, driver, or queue,
  3043.  since these are set by the user.) The application should save with the
  3044.  document any preferences entered by the user. An application can also use
  3045.  DevPostDeviceModes to return the current job properties without displaying
  3046.  any dialog boxes.
  3047.  
  3048.  
  3049.  2.8.2  Printer Device Contexts
  3050.  
  3051.  An application uses the queue and device driver data it retrieves from the
  3052.  initialization files to open a device context for a printer. A device
  3053.  context is a structure containing device-specific information. It acts as a
  3054.  bridge between the presentation space in which an application produces a
  3055.  document and the device that displays or prints the document. When an
  3056.  application associates a presentation space with a screen device context,
  3057.  output goes to the screen; when the presentation space is associated with a
  3058.  printer device context, the output goes to the specified printer. A device
  3059.  context for a printer is specific to a printer device driver and may include
  3060.  information about customizing the print job. For more information about
  3061.  device contexts, see the Microsoft Operating System/2 Programmer's
  3062.  Reference, Volume 1.
  3063.  
  3064.  An application opens a device context for a printer by calling the DevOpenDC
  3065.  function and passing it a pointer to a DEVOPENSTRUC structure. Typically,
  3066.  the application specifies the contents of at least the first four fields in
  3067.  DEVOPENSTRUC (the logical address, the printer-driver name, the driver data,
  3068.  and the data type).
  3069.  
  3070.  Types of Device Contexts
  3071.  
  3072.  The second argument of the DevOpenDC function specifies the type of device
  3073.  context to open. A device context for a printer can have type OD_QUEUED,
  3074.  OD_DIRECT, or OD_INFO.
  3075.  
  3076.  OD_QUEUED is the most common type of printer device context. This type of
  3077.  device context takes advantage of the spooling capabilities of MS OS/2. When
  3078.  an application uses this type, the spooler places print jobs into the print
  3079.  queue. When the spooler determines that the printer is idle, the queue
  3080.  processor either plays the metafile into the printer device context or
  3081.  passes the job as raw data, depending on the data type specified in the
  3082.  DEVOPENSTRUC structure. The printer device driver translates the output of
  3083.  the queue processor into instructions that are meaningful to the printer.
  3084.  Specifying OD_QUEUED allows an application to continue with other tasks once
  3085.  the spooler has put a job into the print queue. Applications should use the
  3086.  OD_QUEUED type of printer device context whenever possible.
  3087.  
  3088.  An application might open an OD_DIRECT printer device context if it needed
  3089.  to bypass the print queue (for example, when printing to a file) or if it
  3090.  needed to perform drawing operations that the system does not support in
  3091.  metafiles. (For a list of metafile restrictions, see Section 2.8.2.5.)
  3092.  
  3093.  An application can use the OD_INFO type to open a device context for
  3094.  information only. For example, an application might use this device context
  3095.  to determine the page size of the current printer; this information would
  3096.  allow the application to provide on-screen pagination information.
  3097.  
  3098.  Logical Address
  3099.  
  3100.  The first field of the DEVOPENSTRUC structure is the pszLogAddress field,
  3101.  which specifies the logical address for the device. The logical address of a
  3102.  printer is the destination for the print data. Generally, this is the queue
  3103.  the user has chosen─for example, LPT1Q. If the application is using a driver
  3104.  that works with ASCII text rather than binary data (for example,
  3105.  pscript.drv), it can direct print output to a file by specifying a filename
  3106.  in this field.
  3107.  
  3108.  Driver Data
  3109.  
  3110.  The third field of the DEVOPENSTRUC structure is the pdriv field, which
  3111.  points to a DRIVDATA structure that describes driver-specific aspects of the
  3112.  page, such as the page layout (portrait or landscape) and the requested
  3113.  paper form. Typically, an application specifies at least the device name and
  3114.  structure size in the DRIVDATA structure, even if the application uses only
  3115.  the default settings for a device driver, because many device drivers
  3116.  support more than one device. If the driver supports only one device, an
  3117.  application can set this field to NULL, causing the device driver to use the
  3118.  default settings stored in os2sys.ini.
  3119.  
  3120.  If an application uses the DevPostDeviceModes function to enable the user to
  3121.  customize the print job, the third field of DEVOPENSTRUC points to the
  3122.  buffer filled by DevPostDeviceModes; the application need not specify fields
  3123.  in the DRIVDATA structure.
  3124.  
  3125.  Data Type
  3126.  
  3127.  The fourth field of the DEVOPENSTRUC structure is the pszDataType field,
  3128.  which specifies the format of the print data. It can be either PM_Q_STD or
  3129.  PM_Q_RAW.
  3130.  
  3131.  When an application specifies PM_Q_STD, the system records the effects of
  3132.  Gpi functions in a metafile. Applications should specify PM_Q_STD whenever
  3133.  possible, because this data format is more versatile and device-independent
  3134.  than is PM_Q_RAW. (If an application requires capabilities that metafiles do
  3135.  not support, it cannot use PM_Q_STD. For more information about metafiles,
  3136.  see Section 2.8.2.5.)
  3137.  
  3138.  When an application specifies PM_Q_RAW, the system performs the graphics
  3139.  rendering immediately. The printer device driver creates a printer-specific
  3140.  data stream and, if the type of the device context is OD_QUEUED, passes the
  3141.  data stream to the spooler. Depending on the type of print job and the
  3142.  driver, creating the spool file could be time-consuming, and the file the
  3143.  driver produces could be very large.
  3144.  
  3145.  Comment
  3146.  
  3147.  The fifth field of the DEVOPENSTRUC structure is the pszComment field, which
  3148.  contains a comment string that identifies the application when a print job
  3149.  is displayed by Print Manager. Typically, the application name is used for
  3150.  this comment. If the application specifies a string in the fourth parameter
  3151.  of the DevEscape function, it should not specify a comment string in the
  3152.  DEVOPENSTRUC structure.
  3153.  
  3154.  
  3155.  2.8.2.1  Printer Device Contexts and Presentation Spaces
  3156.  
  3157.  The DevOpenDC function returns a handle to a device context. An application
  3158.  uses this handle in the call to the GpiCreatePS function that creates a
  3159.  presentation space. When calling GpiCreatePS, the application can associate
  3160.  the presentation space with the device context, by specifying GPIA_ASSOC in
  3161.  the flOptions parameter.
  3162.  
  3163.  When an application specifies GPIA_ASSOC in the call to the GpiCreatePS
  3164.  function, it can specify zero as the width and height in the SIZEL structure
  3165.  pointed to by the second parameter. The SIZEL structure contains the
  3166.  dimensions of the presentation page, which defines how points in the
  3167.  presentation space are mapped to the device. When the application specifies
  3168.  zero for these dimensions, the system makes the presentation space large
  3169.  enough to include one page, as defined by the device context.
  3170.  
  3171.  The presentation-space type must be GPIT_NORMAL (not GPIT_MICRO) when an
  3172.  application creates a presentation space for printing. If the application
  3173.  specifies page units that are absolute measurements─PU_LOENGLISH or
  3174.  PU_HIMETRIC, for example─graphics are the same size in printed output as
  3175.  they are on the screen. If the application specifies PU_PELS, it must apply
  3176.  transformations to the graphics to compensate for the different aspect
  3177.  ratios and resolutions of the screen and printer.
  3178.  
  3179.  An application can use the same presentation space for printing as it used
  3180.  for drawing on the screen. Before the application can associate the
  3181.  presentation space with a printer device context, the presentation space
  3182.  must be disassociated from the previous device context. To do this, the
  3183.  application calls the GpiAssociate function twice: the first time to
  3184.  disassociate the presentation space with the original device context and the
  3185.  second time to associate the presentation space with the printer device
  3186.  context:
  3187.  
  3188.  GpiAssociate(hpsWindow, (HDC) NULL);
  3189.      .
  3190.      .
  3191.      .
  3192.  GpiAssociate(hpsWindow, hdcPrinter);
  3193.  
  3194.  
  3195.  
  3196.  
  3197.  If an application uses the same presentation space for printing and window
  3198.  drawing, it must process messages carefully in order to prevent conflicts
  3199.  between what is displayed on the screen and what is printed. In particular,
  3200.  the presentation space should not respond to a WM_PAINT message while
  3201.  associated with a printer device context.
  3202.  
  3203.  Once the application has associated a presentation space with a printer
  3204.  device context, the application can use graphics functions to draw each page
  3205.  of the document.
  3206.  
  3207.  
  3208.  2.8.2.2  Printing Documents
  3209.  
  3210.  Drawing for printing is similar to drawing in a window the size of a piece
  3211.  of paper. If an application uses device-independent world units to produce
  3212.  graphics, the system automatically scales the output so that the graphics
  3213.  will look the same on any output device; a one-inch circle drawn on the
  3214.  screen is printed as a one-inch circle on a 72-dot-per-inch impact printer
  3215.  or on a 300-dot-per-inch laser printer. For more information on scaling
  3216.  graphics, see the Microsoft Operating System/2 Programmer's Reference,
  3217.  Volume 1.
  3218.  
  3219.  Starting a Print Job
  3220.  
  3221.  Before an application starts drawing graphics in a printer device context,
  3222.  it must use the DevEscape function to issue a DEVESC_STARTDOC escape.
  3223.  DevEscape allows an application to send an escape directly to a device
  3224.  driver─in this case, the escape function tells the printer device driver
  3225.  that the printer should be prepared to print a document.
  3226.  
  3227.  Determining Printer Capabilities and Page Size
  3228.  
  3229.  An application can use the DevQueryHardcopyCaps function to determine the
  3230.  capabilities of the printer associated with the printer device context.
  3231.  DevQueryHardcopyCaps fills one or more HCINFO structures with detailed
  3232.  information about the page type and page dimensions supported by the device.
  3233.  Each HCINFO structure also specifies whether the described configuration is
  3234.  currently selected for that device. For example, an application could call
  3235.  DevQueryHardcopyCaps to fill five HCINFO structures with information about a
  3236.  printer. If the printer supported Letter paper, Legal paper, Landscape
  3237.  paper, Wide paper, and A4 paper, the dimensions of each of these "form
  3238.  names" would be specified, and one of them would be designated as the
  3239.  current choice for that printer.
  3240.  
  3241.  DevQueryHardcopyCaps returns the dimensions of a page in millimeters. If the
  3242.  drawing units in an application's presentation space are absolute values in
  3243.  world space (metric or English), determining the page boundaries in the
  3244.  presentation space requires only a simple conversion.
  3245.  
  3246.  An application could also use the DevQueryCaps function to retrieve the
  3247.  width and height of the printer page in device units. The page size returned
  3248.  reflects either portrait or landscape mode, depending on what the user has
  3249.  selected. To convert device units into world coordinates, the application
  3250.  can call the GpiConvert function.
  3251.  
  3252.  Printing a Page
  3253.  
  3254.  Each page of a print job is drawn by using Gpi functions in a presentation
  3255.  space that has been associated with a printer device context. If a document
  3256.  consists of only one page, the origin of the presentation space's coordinate
  3257.  system typically corresponds to the origin of the device page, so no
  3258.  translation is necessary. To print a multiple-page document, however, an
  3259.  application must translate the world-space coordinates of the presentation
  3260.  space so that a point defining the lower-left corner of the graphic to be
  3261.  printed corresponds to the origin of the device page.
  3262.  
  3263.  An application can determine the best places to divide a large image by
  3264.  using the page size retrieved by the DevQueryHardcopyCaps or DevQueryCaps
  3265.  function. After establishing the page boundaries, the application moves each
  3266.  page to the origin of the coordinate space, calls the DevEscape function to
  3267.  start a new page, and draws the image. To move a page to the origin of the
  3268.  coordinate space, the application calls the GpiQueryDefaultViewMatrix
  3269.  function to fill a MATRIXLF structure with the current transformation
  3270.  values, sets a POINTL structure to values based on the page size and passes
  3271.  a pointer to that structure to the GpiTranslate function, and then calls the
  3272.  GpiSetDefaultViewMatrix function to set the new viewing matrix. For more
  3273.  information about coordinate spaces and transformations, see the Microsoft
  3274.  Operating System/2 Programmer's Reference, Volume 1.
  3275.  
  3276.  To start a new page in a multiple-page document, an application must call
  3277.  DevEscape at the end of each page, specifying the DEVESC_NEWFRAME escape.
  3278.  (The application need not send a DEVESC_NEWFRAME escape after the last page
  3279.  in a document.)
  3280.  
  3281.  Finishing a Print Job
  3282.  
  3283.  After printing every page in a print job, an application must call the
  3284.  DevEscape function, specifying the DEVESC_ENDDOC escape.
  3285.  
  3286.  
  3287.  2.8.2.3  Printing in a Thread
  3288.  
  3289.  Printing typically begins when a user chooses a command from a menu in an
  3290.  application. A client window receives a WM_COMMAND message from the menu and
  3291.  begins the printing operation. The application does not process any further
  3292.  mouse clicks or keystrokes until it calls the WinGetMsg or WinPeekMsg
  3293.  function again. This means that the user cannot interact with the printing
  3294.  application or switch to another application until one of these two
  3295.  functions is called. If the application is not using the spooler and queue
  3296.  processor, or if the print job is lengthy or complicated, the user may have
  3297.  an inconvenient wait before being able to resume work.
  3298.  
  3299.  There are two common methods for allowing an application to remain
  3300.  responsive during a lengthy printing operation:
  3301.  
  3302.    ■   The application can handle user input by calling the WinGetMsg or
  3303.        WinPeekMsg function.
  3304.  
  3305.    ■   The application can create a separate thread to handle printing. The
  3306.        main thread can continue to call the WinGetMsg function while the
  3307.        printing thread is running.
  3308.  
  3309.  
  3310.  
  3311.  
  3312.  Although printing in a thread is the most common way of solving this
  3313.  user-interface problem, handling user input during printing can cause
  3314.  problems with data integrity and synchronization. (For example, a user could
  3315.  attempt to modify a document while it is printing.) An application could use
  3316.  semaphores to protect shared resources whenever there are potential
  3317.  conflicts.
  3318.  
  3319.  Processing WM_PAINT messages is a common problem for applications that print
  3320.  in a thread and that use the same presentation space for both drawing on the
  3321.  screen and printing. An application should not attempt to draw in the window
  3322.  when the presentation space is associated with a printer device context.
  3323.  
  3324.  
  3325.  2.8.2.4  Printing Bitmaps
  3326.  
  3327.  An application must perform the following steps to print a bitmap:
  3328.  
  3329.    1.  Create a device context and presentation space for the printer.
  3330.  
  3331.    2.  Create a memory device context for the printer and associate it with a
  3332.        presentation space. This memory device context should be compatible
  3333.        with the printer device context.
  3334.  
  3335.    3.  Create a bitmap in (or load it into) the printer's memory presentation
  3336.        space.
  3337.  
  3338.    4.  Attach the bitmap to the printer's memory presentation space and
  3339.        device context by calling the GpiSetBitmap function.
  3340.  
  3341.    5.  Draw the bitmap from the printer's memory presentation space and
  3342.        device context to the printer presentation space and device context by
  3343.        using the GpiBitBlt or GpiWCBitBlt function. Do any scaling necessary
  3344.        to correct for resolution differences between the display and the
  3345.        printer.
  3346.  
  3347.  
  3348.  
  3349.  
  3350.  The GpiSetBitmap function converts between different device formats─for
  3351.  example, color to monochrome─but does not correct for differences in pel
  3352.  resolution between devices. For example, if an application prints a screen
  3353.  bitmap (typically about 72 pels per inch) to a laser printer with 300 pels
  3354.  per inch, it must scale the image when converting from the printer's memory
  3355.  device context to the device context. The application can determine the
  3356.  device resolutions by calling the DevQueryCaps function for each device.
  3357.  
  3358.  
  3359.  2.8.2.5  Metafile Restrictions
  3360.  
  3361.  Most applications record print jobs as metafiles, which the queue processor
  3362.  plays into the printer device context when the spooler determines that the
  3363.  printer is idle. Although metafiles are versatile and device-independent,
  3364.  some restrictions apply to their use. If an application can use metafiles in
  3365.  printing, it specifies PM_Q_STD in the DEVOPENSTRUC structure when opening
  3366.  the device context. If the application cannot use metafiles, it specifies
  3367.  PM_Q_RAW.
  3368.  
  3369.  An application should not change any of the following items while drawing in
  3370.  a metafile:
  3371.  
  3372.    ■   The graphics field.
  3373.  
  3374.    ■   The code page for the default character set.
  3375.  
  3376.    ■   The color table. (The size of the color table must not exceed 31K.)
  3377.  
  3378.    ■   The default viewing transformation.
  3379.  
  3380.    ■   The setting of the draw controls. (The DCTL_DISPLAY flag in the
  3381.        GpiSetDrawControl function must be on.)
  3382.  
  3383.    ■   The default values of attributes, viewing limits, primitive tags, and
  3384.        arc parameters.
  3385.  
  3386.  
  3387.  
  3388.  
  3389.  An application should not call the following functions while drawing in a
  3390.  metafile that will be played in a printer device context:
  3391.  
  3392.    ■   DevEscape (for an escape that is stored in a metafile)
  3393.  
  3394.    ■   GpiDeleteSetId
  3395.  
  3396.    ■   GpiErase
  3397.  
  3398.    ■   GpiExcludeClipRectangle
  3399.  
  3400.    ■   GpiIntersectClipRectangle
  3401.  
  3402.    ■   GpiOffsetClipRegion
  3403.  
  3404.    ■   GpiPaintRegion
  3405.  
  3406.    ■   GpiResetPS
  3407.  
  3408.    ■   GpiSetClipRegion
  3409.  
  3410.    ■   GpiSetPel
  3411.  
  3412.    ■   GpiSetPS
  3413.  
  3414.  
  3415.  
  3416.  
  3417.  Because an application should not call the GpiDeleteSetId function when
  3418.  using metafiles for printing, local identifiers cannot be reused inside a
  3419.  print job. If an application uses a bitmap in a GpiWCBitBlt operation or as
  3420.  an area-fill pattern, the application should not modify the bitmap.
  3421.  
  3422.  Applications should not reassociate the presentation space while it is
  3423.  associated with an OD_QUEUED device context.
  3424.  
  3425.  An application should use only these foreground mix modes when using a
  3426.  metafile for printing:
  3427.  
  3428.    ■   FM_DEFAULT
  3429.  
  3430.    ■   FM_LEAVEALONE
  3431.  
  3432.    ■   FM_OR
  3433.  
  3434.    ■   FM_OVERPAINT
  3435.  
  3436.  
  3437.  
  3438.  
  3439.  An application should use only these background mix modes when using a
  3440.  metafile for printing:
  3441.  
  3442.    ■   BM_DEFAULT
  3443.  
  3444.    ■   BM_LEAVEALONE
  3445.  
  3446.    ■   BM_OVERPAINT
  3447.  
  3448.  
  3449.  
  3450.  
  3451.  An application that is using a metafile for printing can use the following
  3452.  escapes in calls to the DevEscape function:
  3453.  
  3454.      DEVESC_ABORTDOC
  3455.      DEVESC_BREAK_EXTRA
  3456.      DEVESC_CHAR_EXTRA
  3457.      DEVESC_DRAFTMODE
  3458.      DEVESC_ENDDOC
  3459.      DEVESC_FLUSHOUTPUT
  3460.      DEVESC_GETSCALINGFACTOR
  3461.      DEVESC_NEWFRAME
  3462.      DEVESC_NEXTBAND
  3463.      DEVESC_QUERYESCSUPPORT
  3464.      DEVESC_QUERYVIOCELLSIZES
  3465.      DEVESC_RAWDATA
  3466.      DEVESC_STARTDOC
  3467.  
  3468.  
  3469.  
  3470.  
  3471.  An application that is using a metafile for printing should not use the
  3472.  following escapes in calls to the DevEscape function:
  3473.  
  3474.      DEVESC_DBE_FIRST
  3475.      DEVESC_DBE_LAST
  3476.      DEVESC_GETCP
  3477.      DEVESC_SETMODE
  3478.      DEVESC_STD_JOURNAL
  3479.  
  3480.  
  3481.  
  3482.  
  3483.  
  3484.  2.8.3  Using Printing
  3485.  
  3486.  The following sections describe the printing procedure of a typical MS OS/2
  3487.  application. Following these procedures allows an application to print to a
  3488.  wide range of output devices.
  3489.  
  3490.  To print graphics output, an application should follow these steps:
  3491.  
  3492.    1.  Determine the job properties of the print job.
  3493.  
  3494.    2.  Determine the capabilities of the available printers.
  3495.  
  3496.    3.  Select a printer by comparing job properties and printer capabilities.
  3497.  
  3498.    4.  Open a device context for the printer.
  3499.  
  3500.    5.  Associate a presentation space with the printer device context.
  3501.  
  3502.    6.  Start the print job.
  3503.  
  3504.    7.  Draw the print job in the presentation space.
  3505.  
  3506.    8.  End the print job.
  3507.  
  3508.    9.  Destroy the printer device context.
  3509.  
  3510.  
  3511.  
  3512.  
  3513.  2.8.3.1  Retrieving Data from Initialization Files
  3514.  
  3515.  The following code fragment shows how to use the PrfQueryProfileString
  3516.  function to retrieve information from the os2.ini and os2sys.ini files. In
  3517.  this case, the code retrieves the default printer and queue:
  3518.  
  3519.  NPSZ npszPrinterName;
  3520.  NPSZ npszDriverName;
  3521.  NPSZ npszModelName;
  3522.  NPSZ npszQueueName;
  3523.  CHAR szPath[80];
  3524.  SHORT i, j;
  3525.  
  3526.  /* Get default printer. */
  3527.  
  3528.  PrfQueryProfileString(
  3529.      HINI_USERPROFILE,           /* query os2.ini           */
  3530.      "PM_SPOOLER",               /* application name        */
  3531.      "PRINTER",                  /* keyname                 */
  3532.      (PSZ) NULL,                 /* error value             */
  3533.      szPath,                     /* buffer receiving string */
  3534.      sizeof(szPath));            /* buffer size             */
  3535.  
  3536.  /* Truncate string at first semicolon. */
  3537.  
  3538.  for (i = 0; (szPath[i] != '\0') && (szPath[i] != ';'); i++);
  3539.  szPath[i] = '\0';
  3540.  
  3541.  /* Copy string */
  3542.  
  3543.  strcpy(npszPrinterName, szPath);
  3544.  
  3545.  /*
  3546.   * Get the default queue in the same way, using "QUEUE" as the
  3547.   * keyname instead of "PRINTER". The following code shows how to get
  3548.   * the name of the printer driver and model information (if any).
  3549.   */
  3550.  
  3551.  PrfQueryProfileString(
  3552.     HINI_SYSTEMPROFILE,          /* query os2sys.ini        */
  3553.     "PM_SPOOLER_QUEUE_DD",       /* application name        */
  3554.     npszQueueName,               /* keyname                 */
  3555.     (PSZ) NULL,                  /* error value             */
  3556.     szPath,                      /* buffer receiving string */
  3557.     sizeof(szPath));             /* buffer size             */
  3558.  
  3559.  /* Parse the driver and model names. */
  3560.  
  3561.  for (i = 0; szPath[i] != '.' && szPath[i] != ';'
  3562.      && szPath[i] != '\0'; i++);
  3563.  
  3564.  if (szPath[i] == '\0')
  3565.      return (ERROR);                        /* no driver or model  */
  3566.  else if (szPath[i] == '.') {               /* if no model name    */
  3567.      szPath[i++] = '\0';
  3568.      strcpy(npszDriverName, szPath);        /* set driver name     */
  3569.      for (j = i; szPath[j] != ';'; j++);    /* find model-name end */
  3570.      szPath[j] = '\0';
  3571.      strcpy(npszModelName, szPath + i);     /* copy model name     */
  3572.  }
  3573.  else {
  3574.      szPath[i] = '\0';
  3575.      strcpy(npszDriverName, szPath);        /* set driver name     */
  3576.      strcpy(npszModelName, npszDriverName); /* model equals driver */
  3577.  }
  3578.  
  3579.  
  3580.  
  3581.  
  3582.  
  3583.  2.8.3.2  Enabling the User to Set Job Properties
  3584.  
  3585.  The following code fragment shows how to use the DevPostDeviceModes function
  3586.  to enable the user to set job properties. This example calls
  3587.  DevPostDeviceModes twice. The first time, the code passes DevPostDeviceModes
  3588.  the names of the device driver, model, and printer that were retrieved by
  3589.  using the PrfQueryProfileString function, and DevPostDeviceModes returns the
  3590.  size of the buffer required to store data from the device driver. After
  3591.  allocating memory for this buffer, the example calls DevPostDeviceModes
  3592.  again, to display the job-properties dialog box. When the user makes choices
  3593.  in the dialog box, DevPostDeviceModes fills the buffer with the job
  3594.  properties.
  3595.  
  3596.  NPSZ npszPrinterName;
  3597.  NPSZ npszDriverName;
  3598.  NPSZ npszModelName;
  3599.  LONG cbBuf;              /* size of buffer for DevPostDeviceModes */
  3600.  PDRIVDATA pdriv;         /* buffer for job properties             */
  3601.  SEL sel;                 /* selector to memory for job properties */
  3602.  
  3603.  cbBuf = DevPostDeviceModes(hab,  /* handle of anchor block        */
  3604.      (PDRIVDATA) NULL,            /* returns size of buffer needed */
  3605.      npszDriverName,              /* driver name                   */
  3606.      npszModelName,               /* device name                   */
  3607.      npszPrinterName,             /* printer name                  */
  3608.      DPDM_POSTJOBPROP);           /* display dialog box            */
  3609.  
  3610.  DosAllocSeg((USHORT) cbBuf, &sel, SEG_NONSHARED);
  3611.  pdriv = MAKEP(sel, 0);
  3612.  
  3613.  DevPostDeviceModes(hab,          /* handle of anchor block        */
  3614.      pdriv,                       /* buffer for driver data        */
  3615.      npszDriverName,              /* driver name                   */
  3616.      npszModelName,               /* device name                   */
  3617.      npszPrinterName,             /* printer name                  */
  3618.      DPDM_POSTJOBPROP);           /* display dialog box            */
  3619.  
  3620.  
  3621.  
  3622.  
  3623.  The second call to the DevPostDeviceModes function fills a buffer with
  3624.  driver data. You can use this buffer when you call the DevOpenDC function to
  3625.  open a device context for the printer.
  3626.  
  3627.  
  3628.  2.8.3.3  Opening a Printer Device Context
  3629.  
  3630.  After the user has chosen the printer to use for the print job and
  3631.  customized the job properties, the application can open a device context for
  3632.  the specified printer device driver. The following code fragment uses the
  3633.  PM_Q_STD data type to open a print job that is stored in the spooler as a
  3634.  metafile. The first two fields of the DEVOPENSTRUC structure are a queue
  3635.  name and driver name that were retrieved in earlier calls to the
  3636.  PrfQueryProfileString function.
  3637.  
  3638.  If the application has used the DevPostDeviceModes function to fill a buffer
  3639.  with job properties, the application passes that buffer to the DevOpenDC
  3640.  function in the third field of the DEVOPENSTRUC structure. Otherwise, this
  3641.  field points to a DRIVDATA structure.
  3642.  
  3643.  HDC hdcPrinter;
  3644.  DEVOPENSTRUC dop;
  3645.  NPSZ npszQueueName;
  3646.  NPSZ npszPrinterName;
  3647.  PDRIVDATA pdriv;
  3648.  
  3649.  dop.pszLogAddress = npszQueueName;  /* logical address (queue name)  */
  3650.  dop.pszDriverName = npszDriverName; /* driver name                   */
  3651.  dop.pdriv         = pdriv;          /* pointer to DRIVDATA structure */
  3652.  dop.pszDataType   = "PM_Q_STD";     /* store job as metafile         */
  3653.  
  3654.  hdcPrinter = DevOpenDC(hab,         /* handle of anchor block        */
  3655.      OD_QUEUED,                      /* uses spooler                  */
  3656.      "*",                            /* does not use os2.ini          */
  3657.      4L,                             /* number of fields used in dop  */
  3658.      (PDEVOPENDATA) &dop,            /* pointer to dop structure      */
  3659.      (HDC) NULL);
  3660.  
  3661.  
  3662.  
  3663.  
  3664.  
  3665.  2.8.3.4  Determining the Page Size
  3666.  
  3667.  After opening a printer device context, the application must determine the
  3668.  page size supported by the printer. The following code fragment shows how to
  3669.  use the DevQueryHardcopyCaps function to determine the width, height, and
  3670.  clipping limits of the current page. DevQueryHardcopyCaps is called twice;
  3671.  the first time it returns the number of forms supported by the printer, and
  3672.  the second time it fills an array of HCINFO structures.
  3673.  
  3674.  HDC hdcPrinter;
  3675.  PHCINFO pahci;
  3676.  SEL sel;
  3677.  SHORT i;
  3678.  LONG cForms, lFormWidth, lFormHeight;
  3679.  LONG lClipLeft, lClipRight, lClipTop, lClipBottom;
  3680.  
  3681.  cForms = DevQueryHardcopyCaps(hdcPrinter,  /* handle of printer DC   */
  3682.      0L,                                    /* from index zero        */
  3683.      0L,                                    /* get all forms          */
  3684.      (PHCINFO) NULL);                       /* no buffer for query    */
  3685.  
  3686.  DosAllocSeg((USHORT) (cForms * sizeof(HCINFO)), &sel, SEG_NONSHARED);
  3687.  pahci = MAKEP(sel, 0);
  3688.  
  3689.  DevQueryHardcopyCaps(hdcPrinter,         /* handle of printer DC     */
  3690.      0L,                                  /* from index zero          */
  3691.      cForms,                              /* number of forms to query */
  3692.      pahci);                              /* structures for forms     */
  3693.  
  3694.  for (i = 0; !pahci[i].flAttributes; i++); /* find current form       */
  3695.  lFormWidth = pahci[i].cx;                 /* get page width (in mm)  */
  3696.  lFormHeight = pahci[i].cy;                /* get page height (in mm) */
  3697.  lClipLeft = pahci[i].xLeftClip;           /* get left clip limit     */
  3698.  lClipRight = pahci[i].xRightClip;         /* get right clip limit    */
  3699.  lClipTop = pahci[i].yTopClip;             /* get top clip limit      */
  3700.  lClipBottom = pahci[i].yBottomClip;       /* get bottom clip limit   */
  3701.  
  3702.  
  3703.  2.8.3.5  Opening a Presentation Space for Printing
  3704.  
  3705.  The following code fragment uses the GpiCreatePS function to open a
  3706.  presentation space for printing. Because GPIA_ASSOC is specified, calling
  3707.  the GpiAssociate function is not required before the application begins
  3708.  drawing to the presentation space. Specifying GPIA_ASSOC also allows the
  3709.  application to specify zero for the fields of the SIZEL structure.
  3710.  
  3711.  HPS hpsPrinter;
  3712.  HDC hdcPrinter;
  3713.  SIZEL sizl;
  3714.  
  3715.  sizl.cx = sizl.cy = 0L;          /* zero because GPI_ASSOC is used   */
  3716.  
  3717.  hpsPrinter = GpiCreatePS(hab,    /* handle of anchor block           */
  3718.      hdcPrinter,                  /* handle of printer device context */
  3719.      &sizl,                       /* pointer to SIZEL structure       */
  3720.      PU_LOENGLISH |               /* drawing units are .01 inches     */
  3721.      GPIT_NORMAL |                /* use normal presentation space    */
  3722.      GPIA_ASSOC);                 /* associate with device context    */
  3723.  
  3724.  
  3725.  2.8.3.6  Printing a Document
  3726.  
  3727.  After you have created a presentation space for drawing and associated it
  3728.  with a printer device context, you can print your document by drawing into
  3729.  the presentation space. Every print job begins with a call to the DevEscape
  3730.  function that specifies the DEVESC_STARTDOC escape and ends with a call to
  3731.  DevEscape that specifies the DEVESC_ENDDOC escape. If the print job is more
  3732.  than one page, the application calls DevEscape and specifies DEVESC_NEWFRAME
  3733.  between each page. (An application need not specify DEVESC_NEWFRAME before
  3734.  the first page of a document or after the last page.)
  3735.  
  3736.  HDC hdcPrinter;
  3737.  
  3738.  DevEscape(hdcPrinter,            /* handle of printer device context */
  3739.      DEVESC_STARTDOC,             /* start the document               */
  3740.      13L,                         /* number of bytes in input data    */
  3741.      (PBYTE) "Test Document",     /* input data                       */
  3742.      (PLONG) NULL,                /* output data                      */
  3743.      (PBYTE) NULL);               /* output data                      */
  3744.      .
  3745.      . /* Draw first page into presentation space.                    */
  3746.      .
  3747.  DevEscape(hdcPrinter,            /* handle of printer device context */
  3748.      DEVESC_NEWFRAME,             /* end page, begin new page         */
  3749.      0L,                          /* other parameters not used        */
  3750.      (PBYTE) NULL,
  3751.      (PLONG) NULL,
  3752.      (PBYTE) NULL);
  3753.      .
  3754.      . /* Draw new pages, calling DEVESC_NEWFRAME before each.        */
  3755.      .
  3756.  DevEscape(hdcPrinter,            /* handle of printer device context */
  3757.      DEVESC_ENDDOC,               /* end the document                 */
  3758.      13L,                         /* number of bytes in input data    */
  3759.      (PBYTE) "Test Document",     /* input data                       */
  3760.      (PLONG) NULL,                /* output data                      */
  3761.      (PBYTE) NULL);               /* output data                      */
  3762.  
  3763.  
  3764.  
  3765.  
  3766.  The third DevEscape parameter is a string displayed by the queue manager as
  3767.  the name of the print job. Typically, the application supplies a filename
  3768.  for this parameter. If an application specifies a string in this parameter,
  3769.  it should not specify a string in the fifth field of the DEVOPENSTRUC
  3770.  structure.
  3771.  
  3772.  If a document is larger than one page, the application must divide it on
  3773.  page boundaries and translate each page to the origin of the device page.
  3774.  The following code fragment demonstrates how to translate a page left by the
  3775.  width of one page. (The SIZEL structure in this code fragment contains the
  3776.  width and height of the device page.) The call to the
  3777.  GpiQueryDefaultViewMatrix function fills a MATRIXLF structure with the
  3778.  current transformation values. GpiTranslate changes the values in the
  3779.  matrix, and GpiSetDefaultViewMatrix makes the changed matrix the new default
  3780.  matrix for the presentation space.
  3781.  
  3782.  MATRIXLF matlf;
  3783.  SIZEL sizl;
  3784.  POINTL ptlTrans;
  3785.  
  3786.  GpiQueryDefaultViewMatrix(
  3787.      hpsPrinter,                     /* handle of presentation space  */
  3788.      9L,                             /* number of items in matrix     */
  3789.      &matlf);                        /* pointer to MATRIXLF structure */
  3790.  
  3791.  ptlTrans.x = -sizl.cx;              /* translate left one page width */
  3792.  ptlTrans.y = 0L;                    /* no vertical translation       */
  3793.  
  3794.  GpiTranslate(hpsPrinter,            /* handle of presentation space  */
  3795.      &matlf,                         /* pointer to MATRIXLF structure */
  3796.      TRANSFORM_REPLACE,              /* replace previous matrix       */
  3797.      &ptlTrans);                     /* pointer to POINTL structure   */
  3798.  
  3799.  GpiSetDefaultViewMatrix(
  3800.      hpsPrinter,                     /* handle of presentation space  */
  3801.      9L,                             /* number of items in matrix     */
  3802.      &matlf,                         /* pointer to MATRIXLF structure */
  3803.      TRANSFORM_REPLACE);             /* replace previous matrix       */
  3804.  
  3805.  
  3806.  
  3807.  
  3808.  
  3809.  2.8.3.7  Printing a Bitmap
  3810.  
  3811.  To print a bitmap, you must create it in or load it into a printer memory
  3812.  presentation space and then use the GpiBitBlt function to copy it to the
  3813.  printer presentation space.
  3814.  
  3815.  When you open the printer's memory device context, you must specify the
  3816.  printer device context as the last parameter of the DevOpenDC function. This
  3817.  ensures that the printer's memory device context is fully compatible with
  3818.  the printer device context.
  3819.  
  3820.  The following code fragment shows how to print a bitmap that was created
  3821.  outside the application. The bitmap resource, identified by the IDD_BITMAP
  3822.  identifier, is loaded by using the GpiLoadBitmap function.
  3823.  
  3824.  POINTL aptl[4];
  3825.  HBITMAP hbm;
  3826.  HDC hdcScreenMem, hdcPrintMem;
  3827.  HPS hpsScreenMem, hpsPrintMem;
  3828.  SIZEL sizl;
  3829.  
  3830.  PSZ apszData[4] = { "DISPLAY", NULL, NULL, NULL };
  3831.  
  3832.  sizl.cx = sizl.cy = 0L;            /* zero because GPI_ASSOC is used */
  3833.  
  3834.  /* Create a DC and PS for the printer.                               */
  3835.  
  3836.  dop.pszLogAddress = npszQueueName;  /* logical address (queue name)  */
  3837.  dop.pszDriverName = npszDriverName; /* driver name                   */
  3838.  dop.pdriv         = pdriv;          /* pointer to DRIVDATA structure */
  3839.  dop.pszDataType   = "PM_Q_STD";     /* stores data as metafile       */
  3840.  
  3841.  hdcPrinter = DevOpenDC(hab, OD_QUEUED, "*", 4L, (PDEVOPENDATA) &dop,
  3842.      (HDC) NULL);
  3843.  
  3844.  hpsPrinter = GpiCreatePS(hab, hdcPrinter, &sizl,
  3845.      PU_PELS | GPIT_NORMAL | GPIA_ASSOC);
  3846.  
  3847.  /* Create a memory DC and PS for the printer.                        */
  3848.  
  3849.  hdcPrintMem = DevOpenDC(hab, OD_MEMORY, "*", 0L, (PDEVOPENDATA) NULL,
  3850.      hdcPrinter);
  3851.  
  3852.  hpsPrintMem = GpiCreatePS(hab, hdcPrintMem, &sizl,
  3853.      PU_PELS | GPIT_NORMAL | GPIA_ASSOC);
  3854.  
  3855.  /* Load the bitmap from the resource into the printer memory PS.     */
  3856.  
  3857.  hbm = GpiLoadBitmap(hpsPrintMem, (HMODULE) NULL, IDD_BITMAP,
  3858.      100L, 100L);
  3859.  
  3860.  /* Set the bitmap for the printer's memory PS.                       */
  3861.  
  3862.  GpiSetBitmap(hpsPrintMem, hbm);
  3863.  
  3864.  /* Send the bitmap from the printer memory PS to the printer PS.     */
  3865.  
  3866.  DevEscape(hdcPrinter, DEVESC_STARTDOC, 13L, /* start document        */
  3867.      (PBYTE) "Test Document", (PLONG) NULL, (PBYTE) NULL);
  3868.  
  3869.  aptl[0].x = aptl[0].y = 100L;     /* lower-left corner target rect.  */
  3870.  aptl[1].x = aptl[1].y = 400L;     /* upper-right corner target rect. */
  3871.  aptl[2].x = aptl[2].y = 0L;       /* lower-left corner source rect.  */
  3872.  aptl[3].x = aptl[3].y = 100L;     /* upper-right corner source rect. */
  3873.  
  3874.  GpiBitBlt(hpsPrinter,             /* destination is printer PS       */
  3875.      hpsPrintMem,                  /* source is printer memory PS     */
  3876.      4L,                           /* no. of points for bitmap sizes  */
  3877.      aptl,                         /* structures for bitmap sizes     */
  3878.      ROP_SRCCOPY,                  /* copy to target                  */
  3879.      BBO_OR);                      /* compression mode                */
  3880.  
  3881.  DevEscape(hdcPrinter, DEVESC_ENDDOC, 13L, /* end document            */
  3882.      (PBYTE) "Test Document", (PLONG) NULL, (PBYTE) NULL);
  3883.  
  3884.  /* Clean up. */
  3885.  
  3886.  GpiSetBitmap(hpsPrintMem, (HBITMAP) NULL);
  3887.  GpiDeleteBitmap(hbm);
  3888.  GpiAssociate(hpsPrinter, (HDC) NULL);
  3889.  GpiDestroyPS(hpsPrinter);
  3890.  GpiAssociate(hpsPrintMem, (HDC) NULL);
  3891.  GpiDestroyPS(hpsPrintMem);
  3892.  DevCloseDC(hdcPrinter);
  3893.  DevCloseDC(hdcPrintMem);
  3894.  
  3895.  
  3896.  
  3897.  
  3898.  
  3899.  2.8.4  Summary
  3900.  
  3901.  Following are the MS OS/2 functions and structures used in printing.
  3902.  
  3903.  
  3904.  2.8.4.1  Printing Functions
  3905.  
  3906.  
  3907.  HMF DevCloseDC(HDC hdc);
  3908.  
  3909.  LONG DevEscape(HDC hdc, LONG cmdCode, LONG cbInData, PBYTE pbInData,
  3910.      PLONG pcbOutData, PBYTE pbOutData);
  3911.  
  3912.  HDC DevOpenDC(HAB hab, LONG type, PSZ pszToken, LONG count,
  3913.      PDEVOPENDATA pbData, HDC hdcComp);
  3914.  
  3915.  LONG DevPostDeviceModes(HAB hab, PDRIVDATA pbDriverData,
  3916.      PSZ pszDriverName, PSZ achDeviceName, PSZ pszName,
  3917.      ULONG flOptions);
  3918.  
  3919.  BOOL DevQueryCaps(HDC hdc, LONG lStartitem, LONG cItems,
  3920.      PLONG alItems);
  3921.  
  3922.  LONG DevQueryHardcopyCaps(HDC hdc, LONG iStartForm, LONG cForms,
  3923.      PHCINFO phci);
  3924.  
  3925.  BOOL GpiAssociate(HPS hps, HDC hdc);
  3926.  
  3927.  BOOL GpiConvert(HPS hps, LONG lSrc, LONG lTarg, LONG cPoints,
  3928.      PPOINTL aptl);
  3929.  
  3930.  HPS GpiCreatePS(HAB hab, HDC hdc, PSIZEL psizl, ULONG flOptions);
  3931.  
  3932.  BOOL GpiDestroyPS(HPS hps);
  3933.  
  3934.  BOOL GpiQueryDefaultViewMatrix(HPS hps, LONG cElements,
  3935.      PMATRIXLF pmatlf);
  3936.  
  3937.  HBITMAP GpiSetBitmap(HPS hps, HBITMAP hbm);
  3938.  
  3939.  BOOL GpiSetDefaultViewMatrix(HPS hps, LONG cElements,
  3940.      PMATRIXLF pmatlf, LONG flType);
  3941.  
  3942.  ULONG PrfQueryProfileString(HINI hini, PSZ pszAppName, PSZ pszKeyName,
  3943.      PSZ pszError, PSZ pszBuf, ULONG cchBuf);
  3944.  
  3945.  
  3946.  
  3947.  
  3948.  
  3949.  2.8.4.2  Printing Structures
  3950.  
  3951.  
  3952.  typedef struct _DEVOPENSTRUC {    /* dop   */
  3953.      PSZ       pszLogAddress;
  3954.      PSZ       pszDriverName;
  3955.      PDRIVDATA pdriv;
  3956.      PSZ       pszDataType;
  3957.      PSZ       pszComment;
  3958.      PSZ       pszQueueProcName;
  3959.      PSZ       pszQueueProcParams;
  3960.      PSZ       pszSpoolerParams;
  3961.      PSZ       pszNetworkParams;
  3962.  } DEVOPENSTRUC;
  3963.  
  3964.  typedef struct _DRIVDATA {        /* driv  */
  3965.      LONG cb;
  3966.      LONG lVersion;
  3967.      CHAR szDeviceName[32];
  3968.      CHAR abGeneralData[1];
  3969.  } DRIVDATA;
  3970.  
  3971.  typedef struct _HCINFO {          /* hci   */
  3972.      CHAR szFormname[32];
  3973.      LONG cx;
  3974.      LONG cy;
  3975.      LONG xLeftClip;
  3976.      LONG yBottomClip;
  3977.      LONG xRightClip;
  3978.      LONG yTopClip;
  3979.      LONG xPels;
  3980.  } HCINFO;
  3981.  
  3982.  typedef struct _MATRIXLF {        /* matlf */
  3983.      FIXED fxM11;
  3984.      FIXED fxM12;
  3985.      LONG  lM13;
  3986.      FIXED fxM21;
  3987.      FIXED fxM22;
  3988.      LONG  lM23;
  3989.      LONG  lM31;
  3990.      LONG  lM32;
  3991.  } MATRIXLF;
  3992.  
  3993.  typedef struct _SIZEL {           /* sizl  */
  3994.      LONG cx;
  3995.      LONG cy;
  3996.  } SIZEL;
  3997.  
  3998.  
  3999.  
  4000.  
  4001.  
  4002.  
  4003.  
  4004.  
  4005.  Chapter 3  Functions and Messages Directory
  4006.  ────────────────────────────────────────────────────────────────────────────
  4007.  
  4008.  
  4009.  
  4010.  
  4011.  3.1  Introduction
  4012.  
  4013.  This chapter describes MS OS/2 system functions and messages that are new or
  4014.  modified for MS OS/2 versions 1.2 and later. The functions provide features,
  4015.  such as multiple-line entry fields, extended attributes for disk files, and
  4016.  application help. The functions and messages represent distinct functional
  4017.  groups.
  4018.  
  4019.  
  4020.  3.1.1  Function Groups
  4021.  
  4022.  Programs use the function groups described in the following list to carry
  4023.  out specific tasks:
  4024.  
  4025.  Function group                    Usage
  4026.  ────────────────────────────────────────────────────────────────────────────
  4027.  
  4028.  Dev                               Use the Presentation Manager device (Dev)
  4029.                                    functions to open and control
  4030.                                    Presentation Manager device drivers.
  4031.                                    These functions let you create device
  4032.                                    contexts that you can associate with a
  4033.                                    presentation space and use with the Gpi
  4034.                                    functions to carry out
  4035.                                    device-independent graphics for displays,
  4036.                                    printers, and plotters.
  4037.  
  4038.  Dos                               Use the disk operating system (Dos)
  4039.                                    functions in full-screen and
  4040.                                    Presentation Manager sessions to read
  4041.                                    from and write to disk files, to
  4042.                                    allocate memory, to start threads and
  4043.                                    processes, to communicate with other
  4044.                                    processes, and to access your computer's
  4045.                                    devices directly. Most functions in this
  4046.                                    group can be used in Presentation
  4047.                                    Manager applications.
  4048.  
  4049.  Gpi                               Use the graphics programming interface (
  4050.                                    Gpi) functions to create graphics output
  4051.                                    for displays, printers, and other output
  4052.                                    devices. The Gpi functions give you a
  4053.                                    full range of graphics primitives, from
  4054.                                    lines to complex curves to bitmaps. You
  4055.                                    choose the attributes for the primitives,
  4056.                                    such as color, line width, and pattern,
  4057.                                    and then draw lines, text, and shapes.
  4058.                                    The retained-graphics capability lets
  4059.                                    you save the drawing in segments and
  4060.                                    build complex pictures by drawing a
  4061.                                    chain of segments.
  4062.  
  4063.  Kbd                               Use the keyboard (Kbd) functions in
  4064.                                    full-screen sessions to read keystrokes
  4065.                                    from the keyboard, to manage multiple
  4066.                                    logical keyboards, and to change code
  4067.                                    pages and translation tables. Because
  4068.                                    the Presentation Manager session
  4069.                                    provides its own keyboard support, Kbd
  4070.                                    functions are not needed in Presentation
  4071.                                    Manager applications.
  4072.  
  4073.  Mou                               Use the mouse (Mou) functions in
  4074.                                    full-screen sessions to read mouse input
  4075.                                    from the mouse-event queue, to set the
  4076.                                    mouse-pointer shape, and to manage the
  4077.                                    mouse for all processes in a session. As
  4078.                                    with the keyboard, the Presentation
  4079.                                    Manager session provides its own mouse
  4080.                                    support, so Mou functions are not needed
  4081.                                    in Presentation Manager applications.
  4082.  
  4083.  Pic                               Use the picture-file (Pic) functions
  4084.                                    when working with picture files,
  4085.                                    typically either metafiles or
  4086.                                    interchange files.
  4087.  
  4088.  Prf                               Use the Profile Manager (Prf) functions
  4089.                                    to open and modify the MS OS/2
  4090.                                    initialization files, os2.ini and
  4091.                                    os2sys.ini. The Prf functions let you
  4092.                                    store application information in the
  4093.                                    initialization files, making that
  4094.                                    information available to other
  4095.                                    applications or to the application
  4096.                                    itself after it has been stopped and
  4097.                                    restarted.
  4098.  
  4099.  Vio                               Use the video input-and-output (Vio)
  4100.                                    functions in full-screen sessions to
  4101.                                    write characters and character
  4102.                                    attributes to the screen, to create
  4103.                                    pop-up windows for messages, to change
  4104.                                    the video modes, and to access physical
  4105.                                    video memory. Vio functions can also be
  4106.                                    used in advanced video-input-and-output
  4107.                                    (AVIO) applications for the Presentation
  4108.                                    Manager session to write characters and
  4109.                                    character attributes in a window. Most
  4110.                                    Presentation Manager applications,
  4111.                                    however, use the graphics programming
  4112.                                    interface (GPI) to write text in a
  4113.                                    window.
  4114.  
  4115.  Win                               Use the window-manager (Win) functions
  4116.                                    to create and manage windows.
  4117.                                    Presentation Manager applications use
  4118.                                    windows as the main interface with the
  4119.                                    user. The Win functions let you create
  4120.                                    menus, scroll bars, and dialog windows
  4121.                                    that let the user choose commands and
  4122.                                    supply input. Your application receives
  4123.                                    all mouse and keyboard input as messages
  4124.                                    from the message queue. Win functions
  4125.                                    let you retrieve messages from the queue
  4126.                                    and dispatch them to the window the
  4127.                                    input is intended for.
  4128.  
  4129.  
  4130.  
  4131.  3.1.2  Message Groups
  4132.  
  4133.  MS OS/2 uses system-defined messages that control the operation of
  4134.  applications. The messages are divided into groups according to the various
  4135.  types of windows that can interpret and process the messages. Applications
  4136.  use the message groups described in the following list to carry out specific
  4137.  tasks:
  4138.  
  4139.  Message group                     Usage
  4140.  ────────────────────────────────────────────────────────────────────────────
  4141.  
  4142.  Combination box                   Use the combination-box control messages
  4143.                                    (CBM_) to control combination boxes.
  4144.  
  4145.  Entry field                       Use the entry-field control messages
  4146.                                    (EM_) to control entry fields.
  4147.  
  4148.  Help Manager                      Use the Help Manager messages (HM_) to
  4149.                                    direct Help Manager for your
  4150.                                    applications.
  4151.  
  4152.  Multiple-line entry field         Use the multiple-line entry-field
  4153.                                    messages (MLM_) to control multiple-line
  4154.                                    entry fields.
  4155.  
  4156.  Menus                             Use the menu messages (MM_) to control
  4157.                                    menus and menu items.
  4158.  
  4159.  Scroll bar                        Use the scroll-bar messages (SBM_) to
  4160.                                    control scroll bars and sliders.
  4161.  
  4162.  Title bar                         Use the title-bar messages (TBM_) to
  4163.                                    control title bars.
  4164.  
  4165.  General                           Use the general window messages (WM_) to
  4166.                                    control the operation of windows of any
  4167.                                    window class. For most general window
  4168.                                    messages, the system sends the message
  4169.                                    to the window procedure of the given
  4170.                                    window. These messages can represent
  4171.                                    input from the keyboard, mouse, or timer.
  4172.                                    Some messages are requests from the
  4173.                                    system to the window procedure for
  4174.                                    information, or they are actions to be
  4175.                                    taken. Other messages contain
  4176.                                    information that the window procedure
  4177.                                    can use or save for processing later.
  4178.  
  4179.  
  4180.  MS OS/2 uses general window messages when creating, destroying, moving,
  4181.  sizing, and activating windows. It also uses these messages for all input to
  4182.  a window, whether the input is from devices, such as the keyboard and mouse,
  4183.  or through other windows, such as dialogs and menus.
  4184.  
  4185.  
  4186.  3.2  Directory
  4187.  
  4188.  The remainder of this chapter is a directory that gives complete syntax,
  4189.  purpose, and parameter descriptions for the new and updated MS OS/2
  4190.  functions and messages. Certain constants that affect several functions have
  4191.  also changed; these are included as separate entries. The types, macros, and
  4192.  structures used by a function are given with the function, and they are
  4193.  described more fully in Chapter 4, "Types, Macros, Structures."
  4194.  
  4195.  You will notice the word New, Change, or Correction on the right side of the
  4196.  line that contains a function or message name. This heading tells you
  4197.  whether that particular entry is new, has been changed or updated, or
  4198.  contains a correction to an error that appeared in MS OS/2 version 1.1
  4199.  documentation.
  4200.  
  4201.  Some of the function and message descriptions in this chapter include
  4202.  examples. The examples show how to use the functions and messages to
  4203.  accomplish simple tasks. In nearly all cases, the examples are code
  4204.  fragments, not complete programs. A code fragment is intended to show the
  4205.  context in which the function or message can be used, but it often assumes
  4206.  that variables, structures, and constants used in the example have been
  4207.  defined and/or initialized. Also, a code fragment may use comments to
  4208.  represent a task instead of giving actual statements.
  4209.  
  4210.  Although the examples are not complete, you can still use them in your
  4211.  programs if you take the following steps:
  4212.  
  4213.    ■   Include the os2.h file in your program.
  4214.  
  4215.    ■   Define the appropriate include constants for the functions,
  4216.        structures, and constants used in the example.
  4217.  
  4218.    ■   Define and initialize all variables.
  4219.  
  4220.    ■   Replace comments that represent tasks with appropriate statements.
  4221.  
  4222.    ■   Check return values for errors and take appropriate actions.
  4223.  
  4224.  
  4225.  
  4226.  
  4227.  3.3  Functions and Messages
  4228.  
  4229.  The following list, in alphabetic order, details the new, changed, and
  4230.  corrected MS OS/2 functions, messages, and constants.
  4231.  
  4232.  
  4233.  █    CBM_HILITE
  4234.  ────────────────────────────────────────────────────────────────────────────
  4235.  
  4236.  
  4237.  CBM_HILITE
  4238.  mp1 = MPFROMSHORT((USHORT) fHilite);    /* highlight flag         */
  4239.  mp2 = 0L;                               /* not used, must be zero */
  4240.  
  4241.  
  4242.  An application sends a CBM_HILITE message to set the highlighting state of
  4243.  the drop-down list button in a combination box that was created with the
  4244.  CBS_DROPDOWN or CBS_DROPDOWNLIST style.
  4245.  
  4246.  
  4247.  Parameters
  4248.  
  4249.  fHilite  Low word of mp1. Specifies whether to highlight or remove
  4250.  highlighting from the drop-down list button. If this parameter is TRUE, the
  4251.  system highlights the button; if the parameter is FALSE, the system removes
  4252.  the highlighting.
  4253.  
  4254.  
  4255.  Return Value
  4256.  
  4257.  The return value is TRUE if the state of the drop-down list button changes
  4258.  or FALSE if it does not.
  4259.  
  4260.  
  4261.  █    CBM_ISLISTSHOWING
  4262.  ────────────────────────────────────────────────────────────────────────────
  4263.  
  4264.  
  4265.  CBM_ISLISTSHOWING
  4266.  mp1 = 0L;    /* not used, must be zero */
  4267.  mp2 = 0L;    /* not used, must be zero */
  4268.  
  4269.  
  4270.  An application sends a CBM_ISLISTSHOWING message to determine whether the
  4271.  list box in a combination box is currently displayed.
  4272.  
  4273.  
  4274.  Parameters
  4275.  
  4276.  This message does not use any parameters.
  4277.  
  4278.  
  4279.  Return Value
  4280.  
  4281.  The return value is TRUE if the list box is displayed or FALSE if it is not.
  4282.  
  4283.  
  4284.  
  4285.  See Also
  4286.  
  4287.  CBM_SHOWLIST
  4288.  
  4289.  
  4290.  █    CBM_SHOWLIST
  4291.  ────────────────────────────────────────────────────────────────────────────
  4292.  
  4293.  
  4294.  CBM_SHOWLIST
  4295.  mp1 = MPFROMSHORT((USHORT) fShow);    /* show flag              */
  4296.  mp2 = 0L;                             /* not used, must be zero */
  4297.  
  4298.  
  4299.  An application sends a CBM_SHOWLIST message to show or hide the list box in
  4300.  a combination box.
  4301.  
  4302.  
  4303.  Parameters
  4304.  
  4305.  fShow  Low word of mp1. Specifies whether to show or hide the list box. If
  4306.  this parameter is TRUE, the list box is shown; otherwise, it is hidden.
  4307.  
  4308.  
  4309.  Return Value
  4310.  
  4311.  The return value is TRUE if the state of the list box changes or FALSE if it
  4312.  does not change.
  4313.  
  4314.  
  4315.  See Also
  4316.  
  4317.  CBM_ISLISTSHOWING
  4318.  
  4319.  
  4320.  █    CBN_EFCHANGE
  4321.  ────────────────────────────────────────────────────────────────────────────
  4322.  
  4323.  
  4324.  WM_CONTROL
  4325.  id = (USHORT) SHORT1FROMMP(mp1);    /* control-window ID */
  4326.  usNotifyCode = CBN_EFCHANGE;
  4327.  
  4328.  
  4329.  The CBN_EFCHANGE notification message is sent when the text in a
  4330.  combination-box entry field changes.
  4331.  
  4332.  
  4333.  Parameters
  4334.  
  4335.  id  Low word of mp1. Identifies the control window.
  4336.  
  4337.  usNotifyCode  High word of mp1. Set to CBN_EFCHANGE.
  4338.  
  4339.  
  4340.  See Also
  4341.  
  4342.  WM_CONTROL
  4343.  
  4344.  
  4345.  █    CBN_EFSCROLL
  4346.  ────────────────────────────────────────────────────────────────────────────
  4347.  
  4348.  
  4349.  WM_CONTROL
  4350.  id = (USHORT) SHORT1FROMMP(mp1);    /* control-window ID */
  4351.  usNotifyCode = CBN_EFSCROLL;
  4352.  
  4353.  
  4354.  The CBN_EFSCROLL notification message is sent when a combination-box entry
  4355.  field is scrolled.
  4356.  
  4357.  
  4358.  Parameters
  4359.  
  4360.  id  Low word of mp1. Identifies the control window.
  4361.  
  4362.  usNotifyCode  High word of mp1. Set to CBN_EFSCROLL.
  4363.  
  4364.  
  4365.  Return Value
  4366.  
  4367.  An application should return zero if it processes this message.
  4368.  
  4369.  
  4370.  See Also
  4371.  
  4372.  WM_CONTROL
  4373.  
  4374.  
  4375.  █    CBN_ENTER
  4376.  ────────────────────────────────────────────────────────────────────────────
  4377.  
  4378.  
  4379.  WM_CONTROL
  4380.  id = (USHORT) SHORT1FROMMP(mp1);    /* control-window ID */
  4381.  usNotifyCode = CBN_ENTER;
  4382.  
  4383.  
  4384.  The CBN_ENTER notification message is sent when the user presses the ENTER
  4385.  key or double-clicks a list item in a combination box.
  4386.  
  4387.  
  4388.  Parameters
  4389.  
  4390.  id  Low word of mp1. Identifies the control window.
  4391.  
  4392.  usNotifyCode  High word of mp1. Set to CBN_ENTER.
  4393.  
  4394.  
  4395.  Return Value
  4396.  
  4397.  An application should return zero if it processes this message.
  4398.  
  4399.  
  4400.  See Also
  4401.  
  4402.  WM_CONTROL
  4403.  
  4404.  
  4405.  █    CBN_LBSCROLL
  4406.  ────────────────────────────────────────────────────────────────────────────
  4407.  
  4408.  
  4409.  WM_CONTROL id = (USHORT) SHORT1FROMMP(mp1);    /* control-window ID */
  4410.  usNotifyCode = CBN_LBSCROLL;
  4411.  
  4412.  
  4413.  The CBN_LBSCROLL notification message is sent when a combination-box list is
  4414.  scrolled.
  4415.  
  4416.  
  4417.  Parameters
  4418.  
  4419.  id  Low word of mp1. Identifies the control window.
  4420.  
  4421.  usNotifyCode  High word of mp1. Set to CBN_LBSCROLL.
  4422.  
  4423.  
  4424.  Return Value
  4425.  
  4426.  An application should return zero if it processes this message.
  4427.  
  4428.  
  4429.  See Also
  4430.  
  4431.  WM_CONTROL
  4432.  
  4433.  
  4434.  █    CBN_LBSELECT
  4435.  ────────────────────────────────────────────────────────────────────────────
  4436.  
  4437.  
  4438.  WM_CONTROL
  4439.  id = (USHORT) SHORT1FROMMP(mp1);    /* control-window ID */
  4440.  usNotifyCode = CBN_LBSELECT;
  4441.  
  4442.  
  4443.  The CBN_LBSELECT notification message is sent when a combination-box list
  4444.  item is selected.
  4445.  
  4446.  
  4447.  Parameters
  4448.  
  4449.  id  Low word of mp1. Identifies the control window.
  4450.  
  4451.  usNotifyCode  High word of mp1. Set to CBN_LBSELECT.
  4452.  
  4453.  
  4454.  Return Value
  4455.  
  4456.  An application should return zero if it processes this message.
  4457.  
  4458.  
  4459.  See Also
  4460.  
  4461.  WM_CONTROL
  4462.  
  4463.  
  4464.  █    CBN_MEMERROR
  4465.  ────────────────────────────────────────────────────────────────────────────
  4466.  
  4467.  
  4468.  WM_CONTROL
  4469.  id = (USHORT) SHORT1FROMMP(mp1);    /* control-window ID */
  4470.  usNotifyCode = CBN_MEMERROR;
  4471.  
  4472.  
  4473.  The CBN_MEMERROR notification message is sent when a combination-box cannot
  4474.  allocate the amount of memory necessary.
  4475.  
  4476.  
  4477.  Parameters
  4478.  
  4479.  id  Low word of mp1. Identifies the control window.
  4480.  
  4481.  usNotifyCode  High word of mp1. Set to CBN_MEMERROR.
  4482.  
  4483.  
  4484.  Return Value
  4485.  
  4486.  An application should return zero if it processes this message.
  4487.  
  4488.  
  4489.  See Also
  4490.  
  4491.  WM_CONTROL
  4492.  
  4493.  
  4494.  █    CBN_SHOWLIST
  4495.  ────────────────────────────────────────────────────────────────────────────
  4496.  
  4497.  
  4498.  WM_CONTROL
  4499.  id = (USHORT) SHORT1FROMMP(mp1);    /* control-window ID */
  4500.  usNotifyCode = CBN_SHOWLIST;
  4501.  
  4502.  
  4503.  The CBN_SHOWLIST notification message is sent when the combination-box list
  4504.  is shown (dropped down).
  4505.  
  4506.  
  4507.  Parameters
  4508.  
  4509.  id  Low word of mp1. Identifies the control window.
  4510.  
  4511.  usNotifyCode  High word of mp1. Set to CBN_SHOWLIST.
  4512.  
  4513.  
  4514.  Return Value
  4515.  
  4516.  An application should return zero if it processes this message.
  4517.  
  4518.  
  4519.  See Also
  4520.  
  4521.  WM_CONTROL
  4522.  
  4523.  
  4524.  █    DevEscape
  4525.  ────────────────────────────────────────────────────────────────────────────
  4526.  
  4527.  LONG DevEscape  (hdc, cmdCode, cbInData, pbInData, pcbOutData, pbOutData)
  4528.  
  4529.  HDC  hdc;                         /*device-context handle */
  4530.  
  4531.  LONG  cmdCode;                    /*escape function to perform */
  4532.  
  4533.  LONG  cbInData;                   /*size of input buffer */
  4534.  
  4535.  PBYTE  pbInData;                  /*pointer to input buffer */
  4536.  
  4537.  PLONG  pcbOutData;                /*pointer to variable for bytes in
  4538.                                    output buffer */
  4539.  
  4540.  PBYTE  pbOutData;                 /*pointer to output-data buffer */
  4541.  
  4542.  
  4543.  The DevEscape function allows applications to access facilities of a device
  4544.  not otherwise available through the API. Because calls to escape functions
  4545.  are generally sent to the device driver, the device driver must be able to
  4546.  use them.
  4547.  
  4548.  
  4549.  Parameters
  4550.  
  4551.  hdc  Identifies the device context.
  4552.  
  4553.  cmdCode  Specifies the escape function to perform. The following escape
  4554.  functions are currently defined:
  4555.  
  4556.       DEVESC_ABORTDOC
  4557.       DEVESC_BREAK_EXTRA
  4558.       DEVESC_CHAR_EXTRA
  4559.       DEVESC_DRAFTMODE
  4560.       DEVESC_ENDDOC
  4561.       DEVESC_FLUSHOUTPUT
  4562.       DEVESC_GETSCALINGFACTOR
  4563.       DEVESC_NEWFRAME
  4564.       DEVESC_NEXTBAND
  4565.       DEVESC_QUERYESCSUPPORT
  4566.       DEVESC_QUERYVIOCELLSIZES
  4567.       DEVESC_RAWDATA
  4568.       DEVESC_STARTDOC
  4569.  
  4570.  
  4571.  
  4572.  
  4573.  Devices can define additional escape functions by using other cmdCode values
  4574.  in the following ranges:
  4575.  
  4576.  Range                             Meaning
  4577.  ────────────────────────────────────────────────────────────────────────────
  4578.  
  4579.  32768-40959                       Not stored in a metafile and not
  4580.                                    recorded.
  4581.  
  4582.  40960-49151                       Stored in a metafile only.
  4583.  
  4584.  49152-57343                       Stored in a metafile and recorded.
  4585.  
  4586.  57344-65535                       Recorded only.
  4587.  
  4588.  
  4589.  
  4590.  cbInData  Specifies the number of bytes of data in the buffer pointed to by
  4591.  the pbInData parameter.
  4592.  
  4593.  pbInData  Points to the buffer that contains the input data required for the
  4594.  escape function.
  4595.  
  4596.  pcbOutData  Points to a variable. When this function is called, the variable
  4597.  specifies the number of bytes of data in the buffer pointed to by the
  4598.  pbOutData parameter. If data is returned in the pbOutData parameter, this
  4599.  variable is updated to the number of bytes of data returned.
  4600.  
  4601.  pbOutData  Points to the buffer that receives the output from the escape
  4602.  function. If this parameter is NULL, no data is returned.
  4603.  
  4604.  
  4605.  Return Value
  4606.  
  4607.  The return value is DEV_OK if the function is successful, DEVESC_ERROR if an
  4608.  error occurs, or DEVESC_NOTIMPLEMENTED if the escape function is not
  4609.  implemented for the specified code.
  4610.  
  4611.  
  4612.  Errors
  4613.  
  4614.  You can use the WinGetLastError function to retrieve the error value, which
  4615.  may be one of the following values:
  4616.  
  4617.       PMERR_ESC_CODE_NOT_SUPPORTED
  4618.       PMERR_INV_ESCAPE_DATA
  4619.       PMERR_INV_HDC
  4620.       PMERR_INV_LENGTH_OR_COUNT
  4621.  
  4622.  
  4623.  
  4624.  
  4625.  
  4626.  Comments
  4627.  
  4628.  The standard escape functions and the corresponding DevEscape parameters are
  4629.  listed in the following paragraphs.
  4630.  
  4631.  DEVESC_BREAK_EXTRA  Defines extra width to add to the break character when
  4632.  that character is transmitted to the device specified by the hdc parameter.
  4633.  The extra width is used in aligning text. The GpiQueryFonts function can be
  4634.  used to determine the break character used in a specific font. For
  4635.  DEVESC_BREAK_EXTRA, the DevEscape parameters contain the following
  4636.  information:
  4637.  
  4638.  Parameter                         Description
  4639.  ────────────────────────────────────────────────────────────────────────────
  4640.  
  4641.  cbInData                          Specifies the number of bytes pointed to
  4642.                                    by the pbInData parameter. This
  4643.                                    parameter must be either zero (for no
  4644.                                    extra spacing) or 4 (for extra spacing).
  4645.  
  4646.  pbInData                          Points to the fixed-point number (FIXED)
  4647.                                    that specifies the amount of extra width
  4648.                                    (in world coordinate units) to add to
  4649.                                    the break character.
  4650.  
  4651.  pcbOutData                        Not used; can be NULL.
  4652.  
  4653.  pbOutData                         Not used; can be zero.
  4654.  
  4655.  Extra spacing is initialized to zero whenever a display context is opened.
  4656.  Any change made to the extra spacing remains in effect until either the
  4657.  display context is closed or a new change to the extra spacing is made.
  4658.  
  4659.  DEVESC_CHAR_EXTRA  Defines extra width to add to all characters when they
  4660.  are transmitted to the device specified by the hdc parameter. The extra
  4661.  width is used in aligning text. For DEVESC_CHAR_EXTRA, the DevEscape
  4662.  parameters contain the following information:
  4663.  
  4664.  Parameter                         Description
  4665.  ────────────────────────────────────────────────────────────────────────────
  4666.  
  4667.  cbInData                          Specifies the number of bytes pointed to
  4668.                                    by the pbInData parameter. This
  4669.                                    parameter must be either zero (for no
  4670.                                    extra spacing) or 4 (for extra spacing).
  4671.  
  4672.  pbInData                          Points to the fixed-point number (FIXED)
  4673.                                    that specifies the amount of extra width
  4674.                                    to be added.
  4675.  
  4676.  pcbOutData                        Not used; can be NULL.
  4677.  
  4678.  pbOutData                         Not used; can be zero.
  4679.  
  4680.  Extra spacing is initialized to zero whenever a display context is opened.
  4681.  Any change made to the extra spacing remains in effect until either the
  4682.  display context is closed or a new change to the extra spacing is made. The
  4683.  extra width added to the break character is the sum of the break-extra and
  4684.  character-extra amounts. Providing a width vector to GpiCharStringPos or
  4685.  GpiQueryCharStringPosAt operates in addition to the extra spacing feature.
  4686.  Extra spacing does not override kerning; extra spacing adjustments and
  4687.  kerning adjustments simply sum. Text drawn in a path is not affected by the
  4688.  extra spacing. This means that outlined text and text used for a clipping
  4689.  region are displayed as if the extra spacing fields were set to zero.
  4690.  
  4691.  DEVESC_QUERYESCSUPPORT  Determines whether the device driver has implemented
  4692.  a particular escape. The return value gives the result. This escape is not
  4693.  stored in a metafile or recorded. For DEVESC_QUERYESCSUPPORT, the DevEscape
  4694.  parameters contain the following information:
  4695.  
  4696.  Parameter                         Description
  4697.  ────────────────────────────────────────────────────────────────────────────
  4698.  
  4699.  cbInData                          Specifies the number of bytes pointed to
  4700.                                    by the pbInData parameter.
  4701.  
  4702.  pbInData                          Specifies the escape-code value of the
  4703.                                    escape function to be checked.
  4704.  
  4705.  pcbOutData                        Not used; can be NULL.
  4706.  
  4707.  pbOutData                         Not used; can be zero.
  4708.  
  4709.  
  4710.  
  4711.  DEVESC_QUERYVIOCELLSIZES  Returns the cell sizes supported by the device
  4712.  identified by the hdc parameter. For DEVESC_QUERYVIOCELLSIZES, the DevEscape
  4713.  parameters contain the following information:
  4714.  
  4715.  Parameter                         Description
  4716.  ────────────────────────────────────────────────────────────────────────────
  4717.  
  4718.  cbInData                          Not used; can be zero.
  4719.  
  4720.  pbInData                          Not used; can be NULL.
  4721.  
  4722.  pcbOutData                        Points to the number of bytes of data
  4723.                                    pointed to by the pbOutData parameter.
  4724.                                    Upon return, this parameter contains the
  4725.                                    number of bytes placed in the buffer
  4726.                                    pointed to by the pbOutData parameter.
  4727.  
  4728.  pbOutData                         Points to the buffer that receives the
  4729.                                    output from this escape function. The
  4730.                                    output is returned in a VIOSIZECOUNT
  4731.                                    structure and an array of
  4732.                                    VIOFONTCELLSIZE structures. These
  4733.                                    structures have the following forms:
  4734.  
  4735.                                        typedef struct _VIOSIZECOUNT {
  4736.                                           LONG maxcount;
  4737.                                           LONG count;
  4738.                                           } VIOSIZECOUNT;
  4739.  
  4740.                                        typedef struct _VIOFONTCELLSIZE {
  4741.                                           LONG cx;
  4742.                                           LONG cy;
  4743.                                           } VIOFONTCELLSIZE;
  4744.  
  4745.  The number of VIOFONTCELLSIZE structures returned is dependent on the value
  4746.  of the count field of the VIOSIZECOUNT structure.
  4747.  
  4748.  For a full description, see Chapter 4, "Types, Macros, Structures."
  4749.  
  4750.  DEVESC_GETSCALINGFACTOR  Returns the scaling factors for the x- and y-axes
  4751.  of a printing device. For each scaling factor, an exponent of two is put in
  4752.  the pbOutData parameter. For example, the value 3 is used if the scaling
  4753.  factor is 8. Scaling factors are used by devices that cannot support
  4754.  graphics at the same resolution as the device resolution. For
  4755.  DEVESC_GETSCALINGFACTOR, the DevEscape parameters contain the following
  4756.  information:
  4757.  
  4758.  Parameter                         Description
  4759.  ────────────────────────────────────────────────────────────────────────────
  4760.  
  4761.  cbInData                          Not used; can be zero.
  4762.  
  4763.  pbInData                          Not used; can be NULL.
  4764.  
  4765.  pcbOutData                        Points to the number of bytes of data
  4766.                                    pointed to by the pbOutData parameter.
  4767.                                    Upon return, this parameter contains the
  4768.                                    number of bytes placed in the buffer
  4769.                                    pointed to by the pbOutData parameter.
  4770.  
  4771.  pbOutData                         Points to the buffer that receives the
  4772.                                    output from this escape. A structure is
  4773.                                    returned that specifies the scaling
  4774.                                    factors for the x- and y-axes.
  4775.  
  4776.  
  4777.  
  4778.  DEVESC_STARTDOC  Indicates the start of a new print job. All subsequent
  4779.  output to the device context, up to the next DEVESC_ENDDOC escape, is
  4780.  spooled under the same job. For DEVESC_STARTDOC, the DevEscape parameters
  4781.  contain the following information:
  4782.  
  4783.  Parameter                         Description
  4784.  ────────────────────────────────────────────────────────────────────────────
  4785.  
  4786.  cbInData                          Specifies the number of bytes pointed to
  4787.                                    by the pbInData parameter.
  4788.  
  4789.  pbInData                          Points to the null-terminated string
  4790.                                    that specifies the name of the document.
  4791.  
  4792.  pcbOutData                        Not used; can be NULL.
  4793.  
  4794.  pbOutData                         Not used; can be NULL.
  4795.  
  4796.  
  4797.  
  4798.  DEVESC_ENDDOC  Ends a print job started by the DEVESC_STARTDOC escape. For
  4799.  DEVESC_ENDDOC, the DevEscape parameters contain the following information:
  4800.  
  4801.  Parameter                         Description
  4802.  ────────────────────────────────────────────────────────────────────────────
  4803.  
  4804.  cbInData                          Not used; can be zero.
  4805.  
  4806.  pbInData                          Not used; can be NULL.
  4807.  
  4808.  pcbOutData                        Points to the buffer that specifies the
  4809.                                    number of characters in the string
  4810.                                    pointed to by the pbOutData parameter.
  4811.                                    This parameter should be NULL if the
  4812.                                    number of characters is zero.
  4813.  
  4814.  pbOutData                         Points to the unsigned 16-bit integer
  4815.                                    that specifies the job identifier if a
  4816.                                    spooler print job was created.
  4817.  
  4818.  
  4819.  
  4820.  DEVESC_NEXTBAND  Allows an application to signal that it has finished
  4821.  writing to a "band," or rectangle. The coordinates of the next band are
  4822.  returned. This escape is used by applications that perform handle banding
  4823.  ("forprinting") themselves. For DEVESC_NEXTBAND, the DevEscape parameters
  4824.  contain the following information:
  4825.  
  4826.  Parameter                         Description
  4827.  ────────────────────────────────────────────────────────────────────────────
  4828.  
  4829.  cbInData                          Not used; can be zero.
  4830.  
  4831.  pbInData                          Not used; can be NULL.
  4832.  
  4833.  pcbOutData                        Points to the number of bytes of data
  4834.                                    pointed to by the pbOutData parameter.
  4835.                                    Upon return, this parameter contains the
  4836.                                    number of bytes placed in the buffer
  4837.                                    pointed to by the pbOutData parameter.
  4838.  
  4839.  pbOutData                         Points to the address of the buffer that
  4840.                                    receives the output from this escape. A
  4841.                                    structure is returned that specifies the
  4842.                                    device coordinates of the next band.
  4843.  
  4844.  
  4845.  
  4846.  DEVESC_ABORTDOC  Stops the current job, erasing everything written by the
  4847.  application to the device since the last call to the DEVESC_ENDDOC escape
  4848.  function. For DEVESC_ABORTDOC, the DevEscape parameters contain the
  4849.  following information:
  4850.  
  4851.  Parameter                         Description
  4852.  ────────────────────────────────────────────────────────────────────────────
  4853.  
  4854.  cbInData                          Not used; can be zero.
  4855.  
  4856.  pbInData                          Not used; can be NULL.
  4857.  
  4858.  pcbOutData                        Not used; can be NULL.
  4859.  
  4860.  pbOutData                         Not used; can be NULL.
  4861.  
  4862.  
  4863.  
  4864.  DEVESC_NEWFRAME  Allows an application to signal when it has finished
  4865.  writing to a page. This escape is typically used with a printer device to
  4866.  advance to a new page. Using this escape is similar to processing the
  4867.  GpiErase function for a screen device context. For DEVESC_NEWFRAME, the
  4868.  DevEscape parameters contain the following information:
  4869.  
  4870.  Parameter                         Description
  4871.  ────────────────────────────────────────────────────────────────────────────
  4872.  
  4873.  cbInData                          Not used; can be zero.
  4874.  
  4875.  pbInData                          Not used; can be NULL.
  4876.  
  4877.  pcbOutData                        Not used; can be NULL.
  4878.  
  4879.  pbOutData                         Not used; can be NULL.
  4880.  
  4881.  
  4882.  
  4883.  DEVESC_DRAFTMODE  Turns draft mode on or off. Turning draft mode on
  4884.  instructs the device driver to print faster and, if necessary, with lower
  4885.  quality. You can change the draft mode only at page boundaries─for example,
  4886.  after a DEVESC_NEWFRAME escape. For DEVESC_DRAFTMODE, the DevEscape
  4887.  parameters contain the following information:
  4888.  
  4889.  Parameter                         Description
  4890.  ────────────────────────────────────────────────────────────────────────────
  4891.  
  4892.  cbInData                          Specifies the number of bytes pointed to
  4893.                                    by the pbInData parameter.
  4894.  
  4895.  pbInData                          Points to the signed 16-bit integer that
  4896.                                    specifies the draft mode. This value is
  4897.                                    1 if draft mode is on and zero if draft
  4898.                                    mode is off.
  4899.  
  4900.  pcbOutData                        Not used; can be NULL.
  4901.  
  4902.  pbOutData                         Not used; can be NULL.
  4903.  
  4904.  
  4905.  
  4906.  DEVESC_FLUSHOUTPUT  Removes any output from the device buffer. For
  4907.  DEVESC_FLUSHOUTPUT, the DevEscape parameters contain the following
  4908.  information:
  4909.  
  4910.  Parameter                         Description
  4911.  ────────────────────────────────────────────────────────────────────────────
  4912.  
  4913.  cbInData                          Not used; can be zero.
  4914.  
  4915.  pbInData                          Not used; can be NULL.
  4916.  
  4917.  pcbOutData                        Not used; can be NULL.
  4918.  
  4919.  pbOutData                         Not used; can be NULL.
  4920.  
  4921.  
  4922.  
  4923.  DEVESC_RAWDATA  Allows an application to send data directly to a device
  4924.  driver. For example, in the case of a printer device driver, the data could
  4925.  be a printer data stream. If raw data is mixed with other data─for example,
  4926.  Gpi data─being sent to the same page of a device context, the results are
  4927.  unpredictable and depend upon the action taken by the Presentation Manager
  4928.  device driver, which, in this case, might ignore the GPI data completely. In
  4929.  general, you should send raw data either to a separate page, using the
  4930.  DEVESC_NEWFRAME escape to obtain a new page, or to a separate document,
  4931.  using the DEVESC_STARTDOC and DEVESC_ENDDOC escapes to create a new
  4932.  document. For DEVESC_RAWDATA, the DevEscape parameters contain the following
  4933.  information:
  4934.  
  4935.  Parameter                         Description
  4936.  ────────────────────────────────────────────────────────────────────────────
  4937.  
  4938.  cbInData                          Specifies the number of bytes pointed to
  4939.                                    by the pbInData parameter.
  4940.  
  4941.  pbInData                          Points to the raw data.
  4942.  
  4943.  pcbOutData                        Not used; can be NULL.
  4944.  
  4945.  pbOutData                         Not used; can be NULL.
  4946.  
  4947.  
  4948.  
  4949.  See Also
  4950.  
  4951.  GpiErase
  4952.  
  4953.  
  4954.  Changes
  4955.  
  4956.  The escape functions DEVESC_BREAK_EXTRA, DEVESC_CHAR_EXTRA, and
  4957.  DEVESC_QUERYVIOCELLSIZES have been added.
  4958.  
  4959.  The DEVESC_STARTDOC and DEVESC_ENDDOC escapes indicate the start and end of
  4960.  a print job.
  4961.  
  4962.  
  4963.  █    DevPostDeviceModes
  4964.  ────────────────────────────────────────────────────────────────────────────
  4965.  
  4966.  LONG DevPostDeviceModes  (hab, pbDriverData, pszDriverName, achDeviceName,
  4967.  pszName, flOptions)
  4968.  
  4969.  HAB  hab;                         /*anchor-block handle */
  4970.  
  4971.  PDRIVDATA  pbDriverData;          /*pointer to buffer for data */
  4972.  
  4973.  PSZ  pszDriverName;               /*pointer to string for driver name */
  4974.  
  4975.  PSZ  achDeviceName;               /*pointer to device name */
  4976.  
  4977.  PSZ  pszName;                     /*pointer to string for output device
  4978.                                    name */
  4979.  
  4980.  ULONG  flOptions;                 /*specifies various options */
  4981.  
  4982.  
  4983.  The DevPostDeviceModes function causes a device driver to post a dialog box
  4984.  so the user can set options for the device (resolution, font cartridges, and
  4985.  so on).
  4986.  
  4987.  The application can call this function first with a NULL data pointer to
  4988.  determine how much storage is needed for the data buffer. It then calls the
  4989.  function a second time to have the buffer filled with data. You can then
  4990.  pass the returned data to the DevOpenDC function as the buffer data pointed
  4991.  to by the pbDriverData parameter.
  4992.  
  4993.  
  4994.  Parameters
  4995.  
  4996.  hab  Identifies the anchor block.
  4997.  
  4998.  pbDriverData  Points to the data buffer that receives device data defined by
  4999.  the driver. If this parameter is NULL, the function returns the required
  5000.  buffer size. The format of the data is the same as for the pbData parameter
  5001.  of the DevOpenDC function.
  5002.  
  5003.  pszDriverName  Points to the null-terminated string that contains the name
  5004.  of the device driver.
  5005.  
  5006.  achDeviceName  Points to the null-terminated string that identifies the
  5007.  particular device (for example, its model number). This string must not
  5008.  exceed 32 bytes. Valid names are defined by device drivers.
  5009.  
  5010.  pszName  Points to the null-terminated string that contains the printer
  5011.  name.
  5012.  
  5013.  flOptions  Specifies whether the function should display a dialog box that
  5014.  allows the user to change job properties, display two dialog boxes that
  5015.  allow the user to change job and printer properties, or simply return the
  5016.  current job properties. This parameter can be one of the following values:
  5017.  
  5018.  Value                             Meaning
  5019.  ────────────────────────────────────────────────────────────────────────────
  5020.  
  5021.  DPDM_POSTJOBPROP                  Display a dialog box that allows the
  5022.                                    user to change job properties. The
  5023.                                    default values for this dialog box are
  5024.                                    taken from the PM_SPOOLER_DD section of
  5025.                                    the os2.ini file if the pszName
  5026.                                    parameter specifies a logical address.
  5027.                                    If pszName is NULL, the default values
  5028.                                    are taken from the pbDriverData
  5029.                                    parameter.
  5030.  
  5031.  DPDM_CHANGEPROP                   Display two dialog boxes. The first
  5032.                                    dialog box allows the user to change job
  5033.                                    properties; the second allows the user
  5034.                                    to change printer properties. The
  5035.                                    default values for these dialog boxes
  5036.                                    are taken from the PM_SPOOLER_DD section
  5037.                                    of the os2.ini file. The function
  5038.                                    returns the new values in the
  5039.                                    pbDriverData parameter. The pszName
  5040.                                    parameter cannot be NULL when this
  5041.                                    option is selected.
  5042.  
  5043.  DPDM_QUERYJOBPROP                 Return the current job properties.
  5044.  
  5045.  
  5046.  
  5047.  Return Value
  5048.  
  5049.  The return value, if the pbDriverData parameter is NULL, is the size (in
  5050.  bytes) required for the data buffer, DPDM_NONE if there are no settable
  5051.  options, or DPDM_ERROR if an error occurs.
  5052.  
  5053.  The return value, if pbDriverData is not NULL, is DEV_OK if the function is
  5054.  successful, DPDM_NONE if there is no device mode, or DPDM_ERROR if an error
  5055.  occurs.
  5056.  
  5057.  
  5058.  Errors
  5059.  
  5060.  Use the WinGetLastError function to retrieve the error value, which may be
  5061.  one of the following:
  5062.  
  5063.       PMERR_INV_DEVICE_NAME
  5064.       PMERR_INV_DRIVER_DATA
  5065.       PMERR_INV_DRIVER_NAME
  5066.       PMERR_INV_LOGICAL_ADDRESS
  5067.  
  5068.  
  5069.  See Also
  5070.  
  5071.  DevOpenDC
  5072.  
  5073.  
  5074.  Corrections
  5075.  
  5076.  The sixth parameter (flOptions) was omitted in the previous description of
  5077.  the function.
  5078.  
  5079.  
  5080.  █    DevQueryCaps
  5081.  ────────────────────────────────────────────────────────────────────────────
  5082.  
  5083.  BOOL DevQueryCaps  (hdc, lStartitem, cItems, alItems)
  5084.  
  5085.  HDC  hdc;                         /*device-context handle */
  5086.  
  5087.  LONG  lStartitem;                 /*first item to be returned */
  5088.  
  5089.  LONG  cItems;                     /*number of items to be returned */
  5090.  
  5091.  PLONG  alItems;                   /*array for device characteristics */
  5092.  
  5093.  
  5094.  The DevQueryCaps function queries the characteristics of the specified
  5095.  device.
  5096.  
  5097.  
  5098.  Parameters
  5099.  
  5100.  hdc  Identifies the device context.
  5101.  
  5102.  lStartitem  Specifies the first item of information to be returned in the
  5103.  array.
  5104.  
  5105.  cItems  Specifies the number of items to be returned in the array.
  5106.  
  5107.  alItems  Points to an array of device characteristics, starting with the
  5108.  item specified by the lStartitem parameter.
  5109.  
  5110.  
  5111.  Return Value
  5112.  
  5113.  The return value is TRUE if the function is successful or FALSE if an error
  5114.  occurs.
  5115.  
  5116.  
  5117.  Errors
  5118.  
  5119.  Use the WinGetLastError function to retrieve the error value, which may be
  5120.  one of the following:
  5121.  
  5122.       PMERR_INV_HDC
  5123.       PMERR_INV_LENGTH_OR_COUNT
  5124.       PMERR_INV_QUERY_ELEMENT_NO
  5125.  
  5126.  
  5127.  
  5128.  
  5129.  
  5130.  Comments
  5131.  
  5132.  The following are possible values for the alItems parameter:
  5133.  
  5134.  CAPS_FAMILY  Specifies the device type. These values are the same as the
  5135.  values for the type parameter in the DevOpenDC function.
  5136.  
  5137.  CAPS_IO_CAPS  Specifies the device input/output capability. The possible
  5138.  values are as follows:
  5139.  
  5140.  Value                             Meaning
  5141.  ────────────────────────────────────────────────────────────────────────────
  5142.  
  5143.  CAPS_IO_DUMMY                     Dummy device
  5144.  
  5145.  CAPS_IO_SUPPORTS_OP               Output
  5146.  
  5147.  CAPS_IO_SUPPORTS_IP               Input
  5148.  
  5149.  CAPS_IO_SUPPORTS_IO               Output and input
  5150.  
  5151.  
  5152.  
  5153.  CAPS_TECHNOLOGY  Specifies the technology. The possible values are as
  5154.  follows:
  5155.  
  5156.  Value                             Meaning
  5157.  ────────────────────────────────────────────────────────────────────────────
  5158.  
  5159.  CAPS_TECH_UNKNOWN                 Unknown (for example, metafile)
  5160.  
  5161.  CAPS_TECH_VECTOR_PLOTTER          Vector plotter
  5162.  
  5163.  CAPS_TECH_RASTER_DISPLAY          Raster display
  5164.  
  5165.  CAPS_TECH_RASTER_PRINTER          Raster printer
  5166.  
  5167.  CAPS_TECH_RASTER_CAMERA           Raster camera
  5168.  
  5169.  CAPS_TECH_POSTSCRIPT              PostScript printer
  5170.  
  5171.  
  5172.  
  5173.  CAPS_DRIVER_VERSION  Specifies the device-driver version number.
  5174.  
  5175.  CAPS_HEIGHT  Specifies the media depth (for a full-screen, maximized window
  5176.  on a display) in pels. (For a plotter, a pel is defined as the smallest
  5177.  possible displacement of the pen and can be smaller than a pen width.)
  5178.  
  5179.  CAPS_WIDTH  Specifies the media width (for a full-screen, maximized window
  5180.  for displays) in pels.
  5181.  
  5182.  CAPS_HEIGHT_IN_CHARS  Specifies the media depth (for a full-screen,
  5183.  maximized window for displays) in character rows, for Vio calls only.
  5184.  
  5185.  CAPS_WIDTH_IN_CHARS  Specifies the media width (for a full-screen, maximized
  5186.  window for displays) in character columns, for Vio calls only.
  5187.  
  5188.  CAPS_HORIZONTAL_FONT_RES  Specifies the horizontal resolution (in pels per
  5189.  inch) for printers; for displays, this value may differ from the actual
  5190.  horizontal device resolution.
  5191.  
  5192.  CAPS_VERTICAL_FONT_RES  Specifies the vertical resolution (in pels per inch)
  5193.  for printers; for displays, this value may differ from the actual vertical
  5194.  device resolution.
  5195.  
  5196.  CAPS_VERTICAL_RESOLUTION  Specifies the vertical resolution (in pels per
  5197.  meter) of the device.
  5198.  
  5199.  CAPS_HORIZONTAL_RESOLUTION  Specifies the horizontal resolution (in pels per
  5200.  meter) of the device.
  5201.  
  5202.  CAPS_CHAR_HEIGHT  Specifies the default height (in pels) of the character
  5203.  box.
  5204.  
  5205.  CAPS_CHAR_WIDTH  Specifies the default width (in pels) of the character box.
  5206.  
  5207.  
  5208.  CAPS_SMALL_CHAR_HEIGHT  Specifies the default height (in pels) of the small
  5209.  character box. This number is zero if there is only one size of the
  5210.  character box.
  5211.  
  5212.  CAPS_SMALL_CHAR_WIDTH  Specifies the default width (in pels) of the small
  5213.  character box. This number is zero if there is only one size of the
  5214.  character box.
  5215.  
  5216.  CAPS_COLORS  Specifies the number of distinct colors supported at the same
  5217.  time, including reset (gray-scales count as distinct colors). If loadable
  5218.  color tables are supported, this is the number of entries in the device
  5219.  color table. For plotters, the value returned is the number of pens plus one
  5220.  (for the background).
  5221.  
  5222.  CAPS_MOUSE_BUTTONS  Specifies the number of mouse or tablet buttons that are
  5223.  available. A returned value of zero indicates that there are no mouse or
  5224.  tablet buttons available.
  5225.  
  5226.  CAPS_FOREGROUND_MIX_SUPPORT  Specifies the foreground-mix support. The
  5227.  possible values are as follows:
  5228.  
  5229.  Value                             Meaning
  5230.  ────────────────────────────────────────────────────────────────────────────
  5231.  
  5232.  CAPS_FM_OR                        OR
  5233.  
  5234.  CAPS_FM_OVERPAINT                 Overpaint
  5235.  
  5236.  CAPS_FM_XOR                       XOR
  5237.  
  5238.  CAPS_FM_LEAVEALONE                Leave-alone
  5239.  
  5240.  CAPS_FM_AND                       AND
  5241.  
  5242.  CAPS_FM_GENERAL_BOOLEAN           Mixes 7 through 17
  5243.  
  5244.  The value returned is the sum of the values appropriate to the mixes
  5245.  supported. A device capable of supporting the OR mix mode must, as a
  5246.  minimum, return 1 + 2 + 16 = 19, signifying support for the mandatory mix
  5247.  modes OR, overpaint, and leave-alone. Note that these numbers correspond to
  5248.  the decimal representation of a bit string that is seven bits long, with
  5249.  each bit set to 1 if the appropriate mode is supported.
  5250.  
  5251.  CAPS_BACKGROUND_MIX_SUPPORT  Specifies the background-mix support. The
  5252.  possible values are as follows:
  5253.  
  5254.  Value                             Meaning
  5255.  ────────────────────────────────────────────────────────────────────────────
  5256.  
  5257.  CAPS_BM_OR                        OR
  5258.  
  5259.  CAPS_BM_OVERPAINT                 Overpaint
  5260.  
  5261.  CAPS_BM_XOR                       XOR
  5262.  
  5263.  CAPS_BM_LEAVEALONE                Leave-alone
  5264.  
  5265.  The value returned is the sum of the values appropriate to the mixes
  5266.  supported. A device must, as a minimum, return 2 + 16 = 18, signifying
  5267.  support for the mandatory background mixes overpaint and leave-alone. Note
  5268.  that these numbers correspond to the decimal representation of a bit string
  5269.  that is five bits long, with each bit set to 1 if the appropriate mode is
  5270.  supported.
  5271.  
  5272.  CAPS_LOADABLE_SYMBOL_SETS  Specifies the number of fonts that may be loaded
  5273.  for VIO.
  5274.  
  5275.  CAPS_WINDOW_BYTE_ALIGNMENT  Specifies whether the client area of VIO windows
  5276.  should be byte-aligned. The possible values are as follows:
  5277.  
  5278.  Value                             Meaning
  5279.  ────────────────────────────────────────────────────────────────────────────
  5280.  
  5281.  CAPS_BYTE_ALIGN_REQUIRED          Must be byte-aligned.
  5282.  
  5283.  CAPS_BYTE_ALIGN_RECOMMENDED       More efficient if byte-aligned, but not
  5284.                                    required.
  5285.  
  5286.  CAPS_BYTE_ALIGN_NOT_REQUIRED      Does not matter whether byte-aligned.
  5287.  
  5288.  
  5289.  
  5290.  CAPS_BITMAP_FORMATS  Specifies the number of bitmap formats supported by the
  5291.  device.
  5292.  
  5293.  CAPS_RASTER_CAPS  Specifies the raster-operations capability of the device.
  5294.  The possible values are as follows:
  5295.  
  5296.  Value                             Meaning
  5297.  ────────────────────────────────────────────────────────────────────────────
  5298.  
  5299.  CAPS_RASTER_BITBLT                BitBlt supported
  5300.  
  5301.  CAPS_RASTER_BANDING               Banding supported
  5302.  
  5303.  CAPS_RASTER_BITBLT_SCALING        Scaling supported
  5304.  
  5305.  CAPS_RASTER_SET_PEL               Set PEL support
  5306.  
  5307.  
  5308.  
  5309.  CAPS_MARKER_WIDTH  Specifies the default width (in pels) of the marker box.
  5310.  
  5311.  CAPS_MARKER_HEIGHT  Specifies the default depth (in pels) of the marker box.
  5312.  
  5313.  
  5314.  CAPS_DEVICE_FONTS  Specifies the number of device-specific fonts.
  5315.  
  5316.  CAPS_GRAPHICS_SUBSET  Specifies the graphics-drawing subset supported (3
  5317.  indicates GOCA DR/3).
  5318.  
  5319.  CAPS_GRAPHICS_VERSION  Specifies the graphics-architecture version supported
  5320.  (1 indicates version 1).
  5321.  
  5322.  CAPS_GRAPHICS_VECTOR_SUBSET  Specifies the graphics-vector-drawing subset
  5323.  supported (2 indicates GOCA VS/2).
  5324.  
  5325.  CAPS_GRAPHICS_CHAR_WIDTH  Specifies the default Gpi character-box width (in
  5326.  pels).
  5327.  
  5328.  CAPS_GRAPHICS_CHAR_HEIGHT  Specifies the default Gpi character-box height
  5329.  (in pels).
  5330.  
  5331.  CAPS_DEVICE_WINDOWING  Specifies the support for device windows. This value
  5332.  may be CAPS_DEV_WINDOWING_SUPPORT if the device supports windowing.
  5333.  
  5334.  CAPS_ADDITIONAL_GRAPHICS  Specifies additional graphics support. The
  5335.  possible values are as follows:
  5336.  
  5337.  Value                             Meaning
  5338.  ────────────────────────────────────────────────────────────────────────────
  5339.  
  5340.  CAPS_GRAPHICS_KERNING_SUPPORT     The device supports kerning.
  5341.  
  5342.  CAPS_FONT_OUTLINE_DEFAULT         Outline font is the default.
  5343.  
  5344.  CAPS_FONT_IMAGE_DEFAULT           Font image is the default.
  5345.  
  5346.  CAPS_SCALED_DEFAULT_MARKERS       Scaled default markers.
  5347.  
  5348.  
  5349.  
  5350.  CAPS_RESERVED  Specifies the maximum number of distinct colors available at
  5351.  one time.
  5352.  
  5353.  CAPS_PHYS_COLORS  Specifies the maximum number of distinct colors that can
  5354.  be specified on the device.
  5355.  
  5356.  CAPS_COLOR_INDEX  Specifies the maximum logical-color-table index supported
  5357.  for the device. This value must be at least 7. For the EGA and VGA device
  5358.  drivers, the value is 63.
  5359.  
  5360.  CAPS_COLOR_PLANES  Specifies the number of color planes.
  5361.  
  5362.  CAPS_COLOR_BITCOUNT  Specifies the number of adjacent color bits for each
  5363.  pel (within one plane).
  5364.  
  5365.  CAPS_COLOR_TABLE_SUPPORT  Specifies the support for loadable color tables.
  5366.  It can be one of the following values:
  5367.  
  5368.  Value                             Meaning
  5369.  ────────────────────────────────────────────────────────────────────────────
  5370.  
  5371.  CAPS_COLTABL_RGB_8                Set if the RGB color table can be loaded,
  5372.                                    with a minimum support of 8 bits each
  5373.                                    for red, green, and blue.
  5374.  
  5375.  CAPS_COLTABLE_RGB_8_PLUS          Set if a color table with other than 8
  5376.                                    bits for each primary color can be
  5377.                                    loaded.
  5378.  
  5379.  CAPS_COLTABLE_TRUE_MIX            Set if true mixing occurs when the
  5380.                                    logical color table has been realized,
  5381.                                    providing that the size of the logical
  5382.                                    color table is not greater than the
  5383.                                    number of distinct colors supported (see
  5384.                                    CAPS_COLORS).
  5385.  
  5386.  CAPS_COLTABL_REALIZE              Set if a loaded color table can be
  5387.                                    realized.
  5388.  
  5389.  
  5390.  
  5391.  See Also
  5392.  
  5393.  DevOpenDC
  5394.  
  5395.  
  5396.  Corrections
  5397.  
  5398.  DevQueryCaps can also retrieve information about colors by using the
  5399.  following constants:
  5400.  
  5401.       CAPS_COLOR_BITCOUNT
  5402.       CAPS_COLOR_PLANES
  5403.       CAPS_COLOR_TABLE_SUPPORT
  5404.       CAPS_COLTABL_REALIZE
  5405.       CAPS_COLTABL_RGB_8
  5406.       CAPS_COLTABLE_RGB_8_PLUS
  5407.       CAPS_COLTABLE_TRUE_MIX
  5408.       CAPS_GRAPHICS_CHAR_WIDTH
  5409.       CAPS_GRAPHICS_CHAR_HEIGHT
  5410.  
  5411.  
  5412.  
  5413.  
  5414.  
  5415.  █    DosAllocHuge
  5416.  ────────────────────────────────────────────────────────────────────────────
  5417.  
  5418.  USHORT DosAllocHuge  (usNumSeg, usPartialSeg, psel, usMaxNumSeg, fsAttr)
  5419.  
  5420.  USHORT  usNumSeg;                 /*number of segments requested */
  5421.  
  5422.  USHORT  usPartialSeg;             /*number of bytes in last segment */
  5423.  
  5424.  PSEL  psel;                       /*pointer to variable for selector
  5425.                                    allocated */
  5426.  
  5427.  USHORT  usMaxNumSeg;              /*maximum number of segments to
  5428.                                    reallocate */
  5429.  
  5430.  USHORT  fsAttr;                   /*shareable/discardable flags */
  5431.  
  5432.  
  5433.  The DosAllocHuge function allocates a huge-memory block. This block consists
  5434.  of one or more 65,536-byte memory segments and one additional segment of a
  5435.  specified size.
  5436.  
  5437.  The DosAllocHuge function allocates the segments and copies the selector of
  5438.  the first segment to the variable pointed to by the psel parameter.
  5439.  Selectors for the remaining segments are consecutive and must be computed by
  5440.  using an offset from the first selector.
  5441.  
  5442.  The DosAllocHuge function can specify that segments can be shared by other
  5443.  processes. If the SEG_GETTABLE flag is used, other processes can gain access
  5444.  to the shared memory by calling the DosGetSeg function. If the SEG_GIVEABLE
  5445.  flag is used, the memory can be shared by other processes after the process
  5446.  allocating the memory has called the DosGiveSeg function. In both cases, the
  5447.  process allocating the memory must pass the selector to the process that
  5448.  will share the memory.
  5449.  
  5450.  The DosAllocHuge function is a family API function.
  5451.  
  5452.  
  5453.  Parameters
  5454.  
  5455.  usNumSeg  Specifies the number of 65,536-byte segments to allocate.
  5456.  
  5457.  usPartialSeg  Specifies the number of bytes in the last segment. This number
  5458.  can be any value in the range 0 through 65,535. If this value is zero, no
  5459.  additional segment is allocated.
  5460.  
  5461.  psel  Points to the variable that receives the selector of the first
  5462.  segment.
  5463.  
  5464.  usMaxNumSeg  Specifies the maximum number of segments that can be specified
  5465.  in any subsequent call to the DosReallocHuge function. If this number is
  5466.  zero, the memory cannot be reallocated to a size greater than its original
  5467.  size, but it can be reallocated to a smaller size.
  5468.  
  5469.  fsAttr  Specifies the segment attributes. This parameter can be one or more
  5470.  of the following values:
  5471.  
  5472.  Value                             Meaning
  5473.  ────────────────────────────────────────────────────────────────────────────
  5474.  
  5475.  SEG_DISCARDABLE                   Creates a discardable, nonshareable
  5476.                                    segment. Once the segment is unlocked,
  5477.                                    it may be discarded to satisfy another
  5478.                                    memory-allocation request.
  5479.  
  5480.  SEG_GETTABLE                      Creates a shareable segment that other
  5481.                                    processes can retrieve by using the
  5482.                                    DosGetSeg function.
  5483.  
  5484.  SEG_GIVEABLE                      Creates a shareable segment that the
  5485.                                    owning process can give to other
  5486.                                    processes by using the DosGiveSeg
  5487.                                    function.
  5488.  
  5489.  SEG_NONSHARED                     Creates a nonshareable, nondiscardable
  5490.                                    segment. This value cannot be combined
  5491.                                    with any other value. .
  5492.  
  5493.  SEG_SIZEABLE                      Specifies that a shared segment can be
  5494.                                    reduced in size by DosReallocSeg.
  5495.  
  5496.  
  5497.  
  5498.  Return Value
  5499.  
  5500.  The return value is zero if the function is successful. Otherwise, it is an
  5501.  error value, which may be the following:
  5502.  
  5503.       ERROR_NOT_ENOUGH_MEMORY
  5504.  
  5505.  
  5506.  
  5507.  
  5508.  
  5509.  Comments
  5510.  
  5511.  Each segment in the huge memory block has a unique selector. The selectors
  5512.  are consecutive. The psel parameter specifies the value of the first
  5513.  selector; the remaining selectors can be computed by adding an offset to the
  5514.  first selector one or more times─that is, once for the second selector,
  5515.  twice for the third, and so on. The selector offset is a multiple of 2, as
  5516.  specified by the shift count retrieved by using the DosGetHugeShift
  5517.  function. For example, if the shift count is 2, the selector offset is 4 (1
  5518.  < 2). If the selector offset is 4 and the first selector is 6, then the
  5519.  second selector is 10, the third is 14, and so on.
  5520.  
  5521.  If necessary, the system will discard an unlocked discardable segment in
  5522.  order to satisfy another allocation request. The new allocation request can
  5523.  come from any process, including the process that allocated the segment
  5524.  being discarded.
  5525.  
  5526.  The DosFreeSeg function frees all segments when passed the first selector.
  5527.  If the segments were declared as shareable, they will not be discarded from
  5528.  memory until the last process using them calls DosFreeSeg.
  5529.  
  5530.  DosAllocHuge can be issued from ring 2, but the segments will be allocated
  5531.  as ring-3 segments.
  5532.  
  5533.  
  5534.  Restrictions
  5535.  
  5536.  In real mode, the following restrictions apply to the DosAllocHuge function:
  5537.  
  5538.  
  5539.    ■   The usPartialSeg parameter is rounded up to the next paragraph
  5540.        (16-byte) value.
  5541.  
  5542.    ■   The actual segment address is copied to the psel parameter.
  5543.  
  5544.  
  5545.  
  5546.  
  5547.  Example
  5548.  
  5549.  This example calls the DosAllocHuge function to allocate two segments with
  5550.  64K and one segment with 200 bytes. It then converts the first selector to a
  5551.  huge pointer that can access all the memory allocated.
  5552.  
  5553.  CHAR huge *pchBuffer;
  5554.  SEL sel;
  5555.  DosAllocHuge(2,               /* number of segments                */
  5556.      200,                      /* size of last segment              */
  5557.      &sel,                     /* address of selector               */
  5558.      5,                        /* maximum segments for reallocation */
  5559.      SEG_NONSHARED);           /* sharing flag                      */
  5560.  pchBuffer = MAKEP(sel, 0);    /* converts selector to pointer      */
  5561.  
  5562.  
  5563.  
  5564.  
  5565.  
  5566.  See Also
  5567.  
  5568.  DosAllocSeg, DosFreeSeg, DosGetHugeShift, DosGetSeg, DosGiveSeg, DosLockSeg,
  5569.  DosReallocHuge, DosUnlockSeg
  5570.  
  5571.  
  5572.  Changes
  5573.  
  5574.  SEG_SIZEABLE is a possible value for the fsAttr parameter. It allows a
  5575.  shared segment to be reduced in size by the DosReallocHuge function.
  5576.  
  5577.  This request can be issued from ring 2, but the segment will be allocated as
  5578.  a ring-3 segment.
  5579.  
  5580.  
  5581.  Corrections
  5582.  
  5583.  The example incorrectly requested three 64K segments instead of the two
  5584.  described.
  5585.  
  5586.  
  5587.  █    DosAllocSeg
  5588.  ────────────────────────────────────────────────────────────────────────────
  5589.  
  5590.  USHORT DosAllocSeg  (usSize, psel, fsAttr)
  5591.  
  5592.  USHORT  usSize;                   /*number of bytes requested */
  5593.  
  5594.  PSEL  psel;                       /*pointer to variable for selector
  5595.                                    allocated */
  5596.  
  5597.  USHORT  fsAttr;                   /*shareable/discardable flags */
  5598.  
  5599.  
  5600.  The DosAllocSeg function allocates a memory segment and copies the segment
  5601.  selector to a specified variable.
  5602.  
  5603.  The DosAllocSeg function can specify that segments can be shared by other
  5604.  processes. If the SEG_GETTABLE flag is used, other processes can gain access
  5605.  to the shared memory by calling the DosGetSeg function. If the SEG_GIVEABLE
  5606.  flag is used, the memory can be shared by other processes after the process
  5607.  allocating the memory has called the DosGiveSeg function. In both cases, the
  5608.  process allocating the memory must pass the selector to the process that
  5609.  will share the memory.
  5610.  
  5611.  The DosAllocSeg function is a family API function.
  5612.  
  5613.  
  5614.  Parameters
  5615.  
  5616.  usSize  Specifies the number of bytes to allocate. This number can be any
  5617.  value in the range 0 through 65,535. If this value is zero, the function
  5618.  allocates 65,536 bytes.
  5619.  
  5620.  psel  Points to the variable that receives the segment selector.
  5621.  
  5622.  fsAttr  Specifies the segment attributes. This parameter can be one or more
  5623.  of the following values:
  5624.  
  5625.  Value                             Meaning
  5626.  ────────────────────────────────────────────────────────────────────────────
  5627.  
  5628.  SEG_DISCARDABLE                   Creates a discardable, nonshareable
  5629.                                    segment. Once the segment is unlocked,
  5630.                                    it may be discarded to satisfy another
  5631.                                    memory-allocation request.
  5632.  
  5633.  SEG_GETTABLE                      Creates a shareable segment that other
  5634.                                    processes can retrieve by using the
  5635.                                    DosGetSeg function.
  5636.  
  5637.  SEG_GIVEABLE                      Creates a shareable segment that the
  5638.                                    owning process can give to other
  5639.                                    processes by using the DosGiveSeg
  5640.                                    function.
  5641.  
  5642.  SEG_NONSHARED                     Creates a nonshareable, nondiscardable
  5643.                                    segment. This value cannot be combined
  5644.                                    with any other value. .
  5645.  
  5646.  SEG_SIZEABLE                      Specifies that a shared segment can be
  5647.                                    reduced in size by DosReallocSeg.
  5648.  
  5649.  
  5650.  
  5651.  Return Value
  5652.  
  5653.  The return value is zero if the function is successful. Otherwise, it is an
  5654.  error value, which may be the following:
  5655.  
  5656.       ERROR_NOT_ENOUGH_MEMORY
  5657.  
  5658.  
  5659.  
  5660.  
  5661.  
  5662.  Comments
  5663.  
  5664.  If the SEG_DISCARDABLE attribute is set, the DosAllocSeg function
  5665.  automatically locks the segment. The segment cannot be discarded until the
  5666.  DosUnlockSeg function is called. Before a process accesses an unlocked
  5667.  discardable segment, it must call the DosLockSeg function to determine
  5668.  whether the segment has been discarded, and to prevent the segment from
  5669.  being discarded while the process is accessing it.
  5670.  
  5671.  If necessary, the system will discard an unlocked discardable segment in
  5672.  order to satisfy another allocation request. The new allocation request can
  5673.  come from any process, including the process that allocated the segment
  5674.  being discarded.
  5675.  
  5676.  The DosFreeSeg function frees the segment. If the segment was declared as
  5677.  shareable, it will not be discarded from memory until the last process using
  5678.  it calls DosFreeSeg.
  5679.  
  5680.  The DosAllocSeg function can allocate only up to 64K of contiguous memory.
  5681.  To allocate more than 64K, use the DosAllocHuge function.
  5682.  
  5683.  DosAllocSeg can be issued from ring 2, but the segment will be allocated as
  5684.  a ring-3 segment.
  5685.  
  5686.  
  5687.  Restrictions
  5688.  
  5689.  In real mode, the following restrictions apply to the DosAllocSeg function:
  5690.  
  5691.    ■   The usSize parameter is rounded up to the next paragraph (16-byte)
  5692.        value.
  5693.  
  5694.    ■   The actual segment address is copied to the psel parameter.
  5695.  
  5696.  
  5697.  
  5698.  
  5699.  Example
  5700.  
  5701.  This example calls the DosAllocSeg function to allocate 26,953 bytes. It
  5702.  then converts the selector to a far pointer that can access the allocated
  5703.  bytes.
  5704.  
  5705.  PCH pchBuffer;
  5706.  SEL sel;
  5707.  
  5708.  DosAllocSeg(26953,            /* bytes to allocate            */
  5709.      &sel,                     /* address of selector          */
  5710.      SEG_NONSHARED);           /* sharing flag                 */
  5711.  pchBuffer = MAKEP(sel, 0);    /* converts selector to pointer */
  5712.  
  5713.  
  5714.  
  5715.  
  5716.  
  5717.  See Also
  5718.  
  5719.  DosAllocHuge, DosAllocShrSeg, DosFreeSeg, DosGetSeg, DosGiveSeg, DosLockSeg,
  5720.  DosReallocSeg, DosUnlockSeg
  5721.  
  5722.  
  5723.  Changes
  5724.  
  5725.  SEG_SIZEABLE is a possible value for the fsAttr parameter. It allows a
  5726.  shared segment to be reduced in size by the DosReallocHuge function.
  5727.  
  5728.  This request can be issued from ring 2, but the segment will be allocated as
  5729.  a ring-3 segment.
  5730.  
  5731.  
  5732.  █    DosAllocShrSeg
  5733.  ────────────────────────────────────────────────────────────────────────────
  5734.  
  5735.  USHORT DosAllocShrSeg  (usSize, pszSegName, psel)
  5736.  
  5737.  USHORT  usSize;                   /*number of bytes requested */
  5738.  
  5739.  PSZ  pszSegName;                  /*pointer to segment name */
  5740.  
  5741.  PSEL  psel;                       /*pointer to variable for selector
  5742.                                    allocated */
  5743.  
  5744.  
  5745.  The DosAllocShrSeg function allocates a shared-memory segment and copies the
  5746.  segment selector to the specified variable.
  5747.  
  5748.  A shared-memory segment can be accessed by any process that can identify the
  5749.  segment name. A process can retrieve a selector for the segment by
  5750.  specifying the name in a call to the DosGetShrSeg function. (Shared segments
  5751.  allocated by using the DosAllocSeg function must be explicitly given or
  5752.  retrieved by using the DosGiveSeg and DosGetSeg functions.)
  5753.  
  5754.  
  5755.  Parameters
  5756.  
  5757.  usSize  Specifies the number of bytes to be allocated. This number can be
  5758.  any value in the range 0 through 65,535. If this value is zero, the function
  5759.  allocates 65,536 bytes.
  5760.  
  5761.  pszSegName  Points to a null-terminated string that identifies the shared
  5762.  memory segment. The string must have the following form:
  5763.  
  5764.  \esharemem\ename
  5765.  
  5766.  The segment name (name) must have the same format as an MS OS/2 filename and
  5767.  must be unique. For example, the name \esharemem\epublic.dat is acceptable.
  5768.  
  5769.  psel  Points to the variable that receives the segment selector.
  5770.  
  5771.  
  5772.  Return Value
  5773.  
  5774.  The return value is zero if the function is successful. Otherwise, it is an
  5775.  error value, which may be one of the following:
  5776.  
  5777.       ERROR_ALREADY_EXISTS
  5778.       ERROR_INVALID_NAME
  5779.       ERROR_NOT_ENOUGH_MEMORY
  5780.  
  5781.  
  5782.  
  5783.  
  5784.  
  5785.  Comments
  5786.  
  5787.  The DosFreeSeg function frees the segment. The segment will not be discarded
  5788.  from memory until the last process using it calls DosFreeSeg.
  5789.  
  5790.  DosAllocShrSeg can be issued from ring 2, but the shared-memory segment will
  5791.  be allocated as a ring-3 segment.
  5792.  
  5793.  
  5794.  Example
  5795.  
  5796.  This example calls the DosAllocShrSeg function to allocate 26,953 bytes. It
  5797.  gives the memory the name "\esharemem\eabc.mem" so that other processes can
  5798.  use the memory if they know the name.
  5799.  
  5800.  SEL sel;
  5801.  
  5802.  DosAllocShrSeg(26953,            /* bytes to allocate   */
  5803.      "\\sharemem\\abc.mem",       /* memory name         */
  5804.      &sel);                       /* selector address    */
  5805.  
  5806.  
  5807.  
  5808.  
  5809.  
  5810.  See Also
  5811.  
  5812.  DosAllocHuge, DosAllocSeg, DosFreeSeg, DosGetSeg, DosGetShrSeg, DosGiveSeg
  5813.  
  5814.  
  5815.  Changes
  5816.  
  5817.  There is no fixed limit to the number of segments a process can allocate.
  5818.  
  5819.  
  5820.  Corrections
  5821.  
  5822.  The error message ERROR_INVALID_HANDLE has been changed to
  5823.  ERROR_INVALID_NAME.
  5824.  
  5825.  
  5826.  █    DosCopy
  5827.  ────────────────────────────────────────────────────────────────────────────
  5828.  
  5829.  USHORT DosCopy  (pszSrc, pszDest, usOpt, ulReserved)
  5830.  
  5831.  PSZ  pszSrc;                      /*pointer to name of source file */
  5832.  
  5833.  PSZ  pszDest;                     /*pointer to name of target file */
  5834.  
  5835.  USHORT  usOpt;                    /*options */
  5836.  
  5837.  ULONG  ulReserved;                /*must be zero */
  5838.  
  5839.  
  5840.  The DosCopy function copies a file or subdirectory.
  5841.  
  5842.  
  5843.  Parameters
  5844.  
  5845.  pszSrc  Points to the null-terminated string that specifies the file or
  5846.  directory to copy. This string must be a valid MS OS/2 filename and cannot
  5847.  contain wildcard characters.
  5848.  
  5849.  pszDest  Points to the null-terminated string that specifies the name of the
  5850.  file, directory, or device to copy the value of pszSrc to. This string must
  5851.  be a valid MS OS/2 filename and cannot contain wildcard characters.
  5852.  
  5853.  usOpt  Specifies an option that can be used in the copy operation (it is
  5854.  ignored if the destination is a device). This parameter can be one of the
  5855.  following values:
  5856.  
  5857.  Value                             Meaning
  5858.  ────────────────────────────────────────────────────────────────────────────
  5859.  
  5860.  DCPY_EXISTING                     Copy the source file to the destination
  5861.                                    file, even if the destination file
  5862.                                    already exists. If neither this option
  5863.                                    nor the DCPY_APPEND option is specified,
  5864.                                    and the file exists, the value
  5865.                                    ERROR_ACCESS_DENIED is returned.
  5866.  
  5867.  DCPY_APPEND                       Append the data in the source file to
  5868.                                    the end of the destination file. If the
  5869.                                    destination file does not exist, a new
  5870.                                    file is created.
  5871.  
  5872.  
  5873.  
  5874.  ulReserved  Specifies a reserved value; must be zero.
  5875.  
  5876.  
  5877.  Return Value
  5878.  
  5879.  The return value is zero if the function is successful. Otherwise, it is an
  5880.  error value, which may be one of the following:
  5881.  
  5882.       ERROR_ACCESS_DENIED
  5883.       ERROR_DIRECTORY
  5884.       ERROR_DRIVE_LOCKED
  5885.       ERROR_FILE_NOT_FOUND
  5886.       ERROR_FILENAME_EXCED_RANGE
  5887.       ERROR_INSUFFICIENT_DISK_SPACE
  5888.       ERROR_INVALID_PARAMETER
  5889.       ERROR_NOT_DOS_DISK
  5890.       ERROR_PATH_NOT_FOUND
  5891.       ERROR_SHARING_BUFFER_EXCEEDED
  5892.       ERROR_SHARING_VIOLATION
  5893.  
  5894.  
  5895.  
  5896.  
  5897.  
  5898.  Comments
  5899.  
  5900.  The DosCopy function can be used to copy individual files or entire
  5901.  directories (including any subdirectories within the directory). The source
  5902.  and destination files can be on different drives.
  5903.  
  5904.  If an I/O error occurs when a file is being copied, the destination file is
  5905.  deleted from the destination directory unless the DCPY_APPEND option is
  5906.  specified. In this case, the destination file is restored to its original
  5907.  size.
  5908.  
  5909.  The DosCopy function copies the attributes of the source to the destination
  5910.  file, except when appending to an existing file.
  5911.  
  5912.  You cannot specify only the drive as the destination. You must give the path
  5913.  on the drive where the file or directory is to be copied.
  5914.  
  5915.  
  5916.  Example
  5917.  
  5918.  This example copies the directory xyz from drive C, including its files and
  5919.  subdirectories, to the root directory on drive A.
  5920.  
  5921.  DosCopy("c:\\xyz",      /* source directory        */
  5922.      "a:\\",             /* destination directory   */
  5923.      DCPY_EXISTING,      /* replaces existing files */
  5924.      0L);                /* reserved                */
  5925.  
  5926.  
  5927.  
  5928.  
  5929.  
  5930.  See Also
  5931.  
  5932.  DosMove
  5933.  
  5934.  
  5935.  █    DosCreateSem
  5936.  ────────────────────────────────────────────────────────────────────────────
  5937.  
  5938.  USHORT DosCreateSem  (fExclusive, phssm, pszSemName)
  5939.  
  5940.  USHORT  fExclusive;               /*exclusive/nonexclusive ownership flag
  5941.                                    */
  5942.  
  5943.  PHSYSSEM  phssm;                  /*pointer to variable for semaphore
  5944.                                    handle */
  5945.  
  5946.  PSZ  pszSemName;                  /*pointer to semaphore name */
  5947.  
  5948.  
  5949.  The DosCreateSem function creates a system semaphore and copies the
  5950.  semaphore handle to a variable. A process can use a system semaphore to
  5951.  indicate to another process a change in the status of a shared resource.
  5952.  
  5953.  
  5954.  Parameters
  5955.  
  5956.  fExclusive  Specifies ownership of the semaphore. If this parameter is
  5957.  CSEM_PRIVATE, the process receives exclusive ownership. If this parameter is
  5958.  CSEM_PUBLIC, the process does not receive exclusive ownership.
  5959.  
  5960.  phssm  Points to the variable that receives the semaphore handle.
  5961.  
  5962.  pszSemName  Points to a null-terminated string that identifies the
  5963.  semaphore. The string must have the form \esem\ename. The string name, name,
  5964.  must have the same format as an MS OS/2 filename and must be unique.
  5965.  
  5966.  
  5967.  Return Value
  5968.  
  5969.  The return value is zero if the function is successful. Otherwise, it is an
  5970.  error value, which may be one of the following:
  5971.  
  5972.       ERROR_ALREADY_EXISTS
  5973.       ERROR_INVALID_NAME
  5974.       ERROR_INVALID_PARAMETER
  5975.       ERROR_TOO_MANY_SEMAPHORES
  5976.  
  5977.  
  5978.  
  5979.  
  5980.  
  5981.  Comments
  5982.  
  5983.  The process calling DosSemCreate receives exclusive ownership of the
  5984.  semaphore if the CSEM_PRIVATE flag is set in the fExclusive parameter.
  5985.  Exclusive ownership prevents other processes from setting or clearing the
  5986.  semaphore. Other processes can open the semaphore and wait for it to change
  5987.  status, but they cannot change its status. Another process can obtain
  5988.  ownership of the semaphore, however, by calling the DosSemRequest function.
  5989.  If ownership of the semaphore changed through DosSemRequest, the process
  5990.  that originally called DosCreateSem no longer has ownership. It cannot
  5991.  change the status of the semaphore until it regains ownership by calling
  5992.  DosSemRequest.
  5993.  
  5994.  
  5995.  Example
  5996.  
  5997.  This example calls DosCreateSem to create a system semaphore, and then calls
  5998.  DosSemSet to set it and DosSemClear to clear it:
  5999.  
  6000.  HSYSSEM hssm;               /* handle to semaphore */
  6001.  DosCreateSem(CSEM_PRIVATE,  /* specifies ownership */
  6002.      &hssm,                  /* address of handle   */
  6003.      "\\sem\\abc.sem");      /* name of semaphore   */
  6004.  DosSemSet(hssm);            /* sets semaphore      */
  6005.      .
  6006.      .
  6007.      .
  6008.  DosSemClear(hssm);          /* clears semaphore    */
  6009.  
  6010.  
  6011.  
  6012.  
  6013.  
  6014.  See Also
  6015.  
  6016.  DosCloseSem, DosMuxSemWait, DosOpenSem, DosSemClear, DosSemRequest,
  6017.  DosSemSet, DosSemSetWait, DosSemWait
  6018.  
  6019.  
  6020.  Corrections
  6021.  
  6022.  The comments incorrectly indicated that the semaphore is always owned by the
  6023.  process that calls DosCreateSem. The semaphore is owned by the calling
  6024.  process only if the CSEM_PRIVATE flag is set in the fExclusive parameter.
  6025.  
  6026.  
  6027.  █    DosCreateThread
  6028.  ────────────────────────────────────────────────────────────────────────────
  6029.  
  6030.  USHORT DosCreateThread  (pfnFunction, ptidThread, pbThrdStack)
  6031.  
  6032.  PFNTHREAD  pfnFunction(VOID);     /*pointer to function */
  6033.  
  6034.  PTID  ptidThread;                 /*pointer to variable for thread
  6035.                                    identifier */
  6036.  
  6037.  PBYTE  pbThrdStack;               /*pointer to thread stack */
  6038.  
  6039.  
  6040.  
  6041.  
  6042.  The DosCreateThread function creates a new thread.
  6043.  
  6044.  
  6045.  Parameters
  6046.  
  6047.  pfnFunction  Points to the application-supplied function and represents the
  6048.  starting address of the thread. For a full description, see the following
  6049.  "Comments" section.
  6050.  
  6051.  ptidThread  Points to the variable that receives the thread identifier.
  6052.  
  6053.  pbThrdStack  Points to the stack of the new thread.
  6054.  
  6055.  
  6056.  Return Value
  6057.  
  6058.  The return value is zero if the function is successful. Otherwise, it is an
  6059.  error value, which may be one of the following:
  6060.  
  6061.       ERROR_NO_PROC_SLOTS
  6062.       ERROR_NOT_ENOUGH_MEMORY
  6063.  
  6064.  
  6065.  
  6066.  
  6067.  
  6068.  Comments
  6069.  
  6070.  When a thread is created, the system makes a far call to the
  6071.  application-supplied function whose address is specified by the pfnFunction
  6072.  parameter. This function can include local variables and can call other
  6073.  functions, as long as the thread's stack has sufficient space. (The stack
  6074.  can be allocated by using the DosAllocSeg function or by using a global
  6075.  array.) The address specified by the pbThrdStack parameter should be the
  6076.  address of the last word in the stack, not the first, because the stack
  6077.  grows down in memory. The thread terminates when the function returns or
  6078.  calls the DosExit function.
  6079.  
  6080.  The pfnFunction parameter points to a function supplied by the program. This
  6081.  function should have the following form:
  6082.  
  6083.  VOID FAR FuncName(VOID)
  6084.  {
  6085.  }
  6086.  
  6087.  
  6088.  
  6089.  
  6090.  Because the system passes no arguments, no parameters are defined.
  6091.  
  6092.  A new thread inherits all files and resources owned by the parent process.
  6093.  Any thread in a process can open a file, device, pipe, queue, or system
  6094.  semaphore. Other threads can use the corresponding handles to access the
  6095.  given item.
  6096.  
  6097.  Note that high-level languages, run-time libraries, and stack checking may
  6098.  severely limit or eliminate the ability to call the DosCreateThread function
  6099.  directly from a high-level-language program. For more information, consult
  6100.  the documentation that came with your language product.
  6101.  
  6102.  Before calling the DosCreateThread function, set the es register to zero or
  6103.  assign to it a selector that will remain valid for the duration of the new
  6104.  thread. If you fail to set the es register to one of these values, the
  6105.  thread may unexpectedly terminate as a result of a general protection fault.
  6106.  
  6107.  
  6108.  
  6109.  Example
  6110.  
  6111.  This example sets aside a 4K buffer to be used as stack space for the
  6112.  thread. The thread is created by calling the DosCreateThread function. The
  6113.  thread terminates by calling the DosExit function.
  6114.  
  6115.  VOID FAR Thread();
  6116.  BYTE abStackArea[4096];        /* global array used as the thread's stack */
  6117.      .
  6118.      .
  6119.      .
  6120.      TID tidThread;
  6121.  
  6122.      DosCreateThread(Thread,                    /* name of thread function */
  6123.          &tidThread,                            /* address of thread ID    */
  6124.          abStackArea + sizeof(abStackArea));    /* thread's stack          */
  6125.      .
  6126.      .
  6127.      .
  6128.  }
  6129.  
  6130.  VOID FAR Thread() {
  6131.      .
  6132.      .
  6133.      .
  6134.      DosExit(EXIT_THREAD, 0);
  6135.  }
  6136.  
  6137.  
  6138.  
  6139.  
  6140.  
  6141.  See Also
  6142.  
  6143.  DosAllocSeg, DosExit, DosResumeThread, DosSuspendThread
  6144.  
  6145.  
  6146.  Corrections
  6147.  
  6148.  The example indicated that a 512-byte stack was allocated. This has been
  6149.  changed to a 4K stack.
  6150.  
  6151.  
  6152.  █    DosDevIOCtl2
  6153.  ────────────────────────────────────────────────────────────────────────────
  6154.  
  6155.  USHORT DosDevIOCtl2  (pvData, cbData, pvParmList, cbParmList, usFunct,
  6156.  usCat, hDev)
  6157.  
  6158.  PVOID  pvData;                    /*pointer to buffer for data */
  6159.  
  6160.  USHORT  cbData;                   /*length of data buffer */
  6161.  
  6162.  PVOID  pvParmList;                /*pointer to list of parameters */
  6163.  
  6164.  USHORT  cbParmList;               /*length of parameter list */
  6165.  
  6166.  USHORT  usFunct;                  /*function code */
  6167.  
  6168.  USHORT  usCat;                    /*device category */
  6169.  
  6170.  HFILE  hDev;                      /*device handle */
  6171.  
  6172.  
  6173.  The DosDevIOCtl2 function performs control functions on the device specified
  6174.  by the file or device handle.
  6175.  
  6176.  
  6177.  Parameters
  6178.  
  6179.  pvData  Points to a data buffer.
  6180.  
  6181.  cbData  Specifies the length (in bytes) of the data buffer.
  6182.  
  6183.  pvParmList  Points to an argument list for a specified command.
  6184.  
  6185.  cbParmList  Specifies the length (in bytes) of the argument list for a
  6186.  specified command.
  6187.  
  6188.  usFunct  Specifies a function code for a specified device. This parameter
  6189.  can be any value from 0 through 255.
  6190.  
  6191.  usCat  Specifies a device category. This parameter can be any value from 0
  6192.  through 255.
  6193.  
  6194.  hDev  Identifies the device. This handle must have been created previously
  6195.  by using the DosOpen function.
  6196.  
  6197.  
  6198.  Return Value
  6199.  
  6200.  The return value is zero if the function is successful. Otherwise, it is an
  6201.  error value, which may be one of the following:
  6202.  
  6203.       ERROR_INVALID_CATEGORY
  6204.       ERROR_INVALID_DRIVE
  6205.       ERROR_INVALID_FUNCTION
  6206.       ERROR_INVALID_HANDLE
  6207.       ERROR_INVALID_PARAMETER
  6208.  
  6209.  
  6210.  
  6211.  
  6212.  
  6213.  Comments
  6214.  
  6215.  This function provides a way for a program to implement a customized IOCtl
  6216.  function.
  6217.  
  6218.  If the pvData parameter is zero, this parameter is not defined for the IOCtl
  6219.  function being specified, and the value passed in the cbData parameter is
  6220.  ignored.
  6221.  
  6222.  If the pvParmList parameter is zero, this parameter is not defined for the
  6223.  IOCtl function being specified, and the value passed in the cbParmList
  6224.  parameter is ignored.
  6225.  
  6226.  Whenever the pvData or pvParmList parameter is a value other than zero, the
  6227.  associated length parameter cannot be zero. The length parameters are not
  6228.  passed to device drivers that do not support them.
  6229.  
  6230.  
  6231.  See Also
  6232.  
  6233.  DosDevIOCtl
  6234.  
  6235.  
  6236.  █    DosEditName
  6237.  ────────────────────────────────────────────────────────────────────────────
  6238.  
  6239.  USHORT DosEditName  (usEditLevel, pszSrc, pszEdit, pszDst, cbDst)
  6240.  
  6241.  USHORT  usEditLevel;              /*edit level */
  6242.  
  6243.  PSZ  pszSrc;                      /*pointer to source string */
  6244.  
  6245.  PSZ  pszEdit;                     /*pointer to editing string */
  6246.  
  6247.  PBYTE  pszDst;                    /*pointer to target buffer */
  6248.  
  6249.  USHORT  cbDst;                    /*length of target buffer */
  6250.  
  6251.  
  6252.  The DosEditName function copies a source string to a revised destination
  6253.  string by using an editing string and rules for converting wildcard
  6254.  characters.
  6255.  
  6256.  
  6257.  Parameters
  6258.  
  6259.  usEditLevel  Specifies the version of editing semantics to use in changing
  6260.  the copy of the source string. (Editing semantics are the rules used by the
  6261.  system to convert wildcard characters.) For MS OS/2 versions 1.2 and later,
  6262.  this parameter must be 0x0001.
  6263.  
  6264.  pszSrc  Points to the null-terminated string to copy. The string should
  6265.  contain only the component of the path to be edited, not the entire path.
  6266.  
  6267.  pszEdit  Points to the null-terminated string to use for editing.
  6268.  
  6269.  pszDst  Points to the buffer that contains the new string.
  6270.  
  6271.  cbDst  Specifies the length (in bytes) of the buffer pointed to by the
  6272.  pszDst parameter.
  6273.  
  6274.  
  6275.  Return Value
  6276.  
  6277.  The return value is zero if the function is successful. Otherwise, it is an
  6278.  error value, which may be one of the following:
  6279.  
  6280.       ERROR_INVALID_NAME
  6281.       ERROR_INVALID_PARAMETER
  6282.  
  6283.  
  6284.  
  6285.  
  6286.  
  6287.  Comments
  6288.  
  6289.  For MS OS/2 versions 1.2 and later, the destination string is always
  6290.  converted to uppercase.
  6291.  
  6292.  The DosEditName function is typically used in copy and rename/move
  6293.  operations.
  6294.  
  6295.  
  6296.  Example
  6297.  
  6298.  This example takes the source name abc.txt and an editing string of *.doc
  6299.  and calls DosEditName to produce the string ABC.DOC:
  6300.  
  6301.  CHAR szDst[14];
  6302.  
  6303.  DosEditName(1, "abc.txt", "*.doc", szDst, sizeof (szDst));
  6304.  
  6305.  
  6306.  
  6307.  
  6308.  
  6309.  █    DosEnterCritSec
  6310.  ────────────────────────────────────────────────────────────────────────────
  6311.  
  6312.  USHORT DosEnterCritSec  (VOID)
  6313.  
  6314.  
  6315.  
  6316.  The DosEnterCritSec function suspends execution of all threads in the
  6317.  current process, except for the calling thread. Suspended threads cannot
  6318.  execute until the current thread calls the DosExitCritSec function.
  6319.  
  6320.  This function has no parameters.
  6321.  
  6322.  
  6323.  Return Value
  6324.  
  6325.  The return value is zero if the function is successful. Otherwise, it is an
  6326.  error value, which may be the following:
  6327.  
  6328.       ERROR_CRITSEC_OVERFLOW
  6329.  
  6330.  
  6331.  
  6332.  
  6333.  
  6334.  Comments
  6335.  
  6336.  The signal handler (if installed) is not suspended when the DosEnterCritSec
  6337.  function is called. If a signal occurs, the processing done by the signal
  6338.  handler must not interfere with the processing done by the thread calling
  6339.  the DosEnterCritSec function.
  6340.  
  6341.  MS OS/2 maintains the number of outstanding DosEnterCritSec requests. This
  6342.  count is incremented by DosEnterCritSec requests and decremented by
  6343.  DosExitCritSec requests. If the count is greater than zero, a DosExitCritSec
  6344.  request will not restore normal thread execution. If the count exceeds
  6345.  65,535, the error ERROR_CRITSEC_OVERFLOW will be returned.
  6346.  
  6347.  
  6348.  See Also
  6349.  
  6350.  DosCreateThread, DosExitCritSec, DosHoldSignal, DosSetSigHandler
  6351.  
  6352.  
  6353.  Changes
  6354.  
  6355.  DosEnterCritSec now returns zero if the function is successful. Otherwise,
  6356.  it returns an error value. It did not return a value in earlier versions.
  6357.  
  6358.  For MS OS/2 versions 1.2 and later, a count is maintained of the number of
  6359.  times DosEnterCritSec is called. Normal thread execution is not restored
  6360.  until an equal number of calls are made to DosExitCritSec.
  6361.  
  6362.  
  6363.  █    DosEnumAttribute
  6364.  ────────────────────────────────────────────────────────────────────────────
  6365.  
  6366.  USHORT DosEnumAttribute  (usRefType, pvFile, ulEntry, pvBuf, cbBuf,
  6367.  pulCount, ulInfoLevel, ulReserved)
  6368.  
  6369.  USHORT  usRefType;                /*reference type */
  6370.  
  6371.  PVOID  pvFile;                    /*filename/handle */
  6372.  
  6373.  ULONG  ulEntry;                   /*starting entry in list */
  6374.  
  6375.  PVOID  pvBuf;                     /*data buffer */
  6376.  
  6377.  ULONG  cbBuf;                     /*buffer size */
  6378.  
  6379.  PULONG  pulCount;                 /*number of entries to return */
  6380.  
  6381.  ULONG  ulInfoLevel;               /*info level */
  6382.  
  6383.  ULONG  ulReserved;                /*reserved */
  6384.  
  6385.  
  6386.  The DosEnumAttribute function enumerates extended attributes for a specified
  6387.  file or subdirectory.
  6388.  
  6389.  The DosEnumAttribute function is a family API function.
  6390.  
  6391.  
  6392.  Parameters
  6393.  
  6394.  usRefType  Specifies whether the pvFile parameter points to a file handle or
  6395.  to a string that contains a file or directory name. This parameter can be
  6396.  one of the following values:
  6397.  
  6398.  Value                             Meaning
  6399.  ────────────────────────────────────────────────────────────────────────────
  6400.  
  6401.  ENUMEA_REFTYPE_FHANDLE            A handle
  6402.  
  6403.  ENUMEA_REFTYPE_PATH               File or directory name
  6404.  
  6405.  
  6406.  
  6407.  pvFile  Points to the handle obtained from the DosOpen or DosOpen2 function
  6408.  or to a null-terminated string that contains a file or directory name.
  6409.  
  6410.  ulEntry  Specifies where to start enumerating extended attributes. A value
  6411.  of 1 specifies the first attribute for the file.
  6412.  
  6413.  pvBuf  Points to the buffer that receives the extended attributes. For a
  6414.  ENUMEA_LEVEL_NO_VALUE-level request, the buffer is in the form of a DENA1
  6415.  structure that contains only the names of the extended attributes. The DENA1
  6416.  structure has the following form:
  6417.  
  6418.  typedef struct _DENA1 {
  6419.      UCHAR  reserved;
  6420.      UCHAR  cbName;
  6421.      USHORT cbValue;
  6422.      UCHAR  szName[1];
  6423.  } DENA1;
  6424.  
  6425.  
  6426.  
  6427.  
  6428.  For a full description, see Chapter 4, "Types, Macros, Structures."
  6429.  
  6430.  cbBuf  Specifies the length (in bytes) of the buffer pointed to by the pvBuf
  6431.  parameter.
  6432.  
  6433.  pulCount  Points to the variable that specifies the number of extended
  6434.  attributes requested and, on return, contains the number retrieved. A value
  6435.  of 0xFFFFFFFF returns as many extended attributes as will fit in the
  6436.  supplied buffer.
  6437.  
  6438.  ulInfoLevel  Specifies the information level requested. For MS OS/2 versions
  6439.  1.2 and later, the only possible value is ENUMEA_LEVEL_NO_VALUE.
  6440.  
  6441.  ulReserved  Specifies a reserved value; must be zero.
  6442.  
  6443.  
  6444.  Return Value
  6445.  
  6446.  The return value is zero if the function is successful. Otherwise, it is an
  6447.  error value, which may be one of the following:
  6448.  
  6449.       ERROR_FILENAME_EXCED_RANGE
  6450.       ERROR_INVALID_HANDLE
  6451.       ERROR_ACCESS_DENIED
  6452.       ERROR_PATH_NOT_FOUND
  6453.       ERROR_NOT_ENOUGH_MEMORY
  6454.       ERROR_INVALID_LEVEL
  6455.       ERROR_INVALID_PARAMETER
  6456.       ERROR_BUFFER_OVERFLOW
  6457.  
  6458.  
  6459.  
  6460.  
  6461.  
  6462.  Comments
  6463.  
  6464.  The order in which attributes are returned may not be the same if the
  6465.  DosEnumAttribute function is called a second time, because other threads or
  6466.  processes may have changed the order.
  6467.  
  6468.  
  6469.  Example
  6470.  
  6471.  This example allocates 1K of memory for the extended-attribute names, calls
  6472.  DosEnumAttribute to retrieve the extended-attribute names for the file
  6473.  eafile, and then displays the names one at a time:
  6474.  
  6475.  #define BUFSIZE 1024
  6476.  
  6477.  SEL sel;
  6478.  PDENA1 pdena1;
  6479.  ULONG ulCount;
  6480.  USHORT offset = 0;
  6481.  
  6482.  DosAllocSeg(BUFSIZE, &sel, SEG_NONSHARED); /* allocates buffer        */
  6483.  pdena1 = MAKEP(sel, 0);              /* initializes pointer to buffer */
  6484.  ulCount = 0xFFFFFFFF;
  6485.  if (!DosEnumAttribute(ENUMEA_REFTYPE_PATH,           /* path supplied */
  6486.          "eafile",                                    /* filename      */
  6487.          1L,                     /* starts enum. with first attr.      */
  6488.          pdena1,                 /* buffer address                     */
  6489.          BUFSIZE,                /* buffer size                        */
  6490.          &ulCount,               /* number of attributes to retrieve   */
  6491.          ENUMEA_LEVEL_NO_VALUE,  /* type of request                    */
  6492.          0L)) {                  /* reserved                           */
  6493.      while (ulCount--) {         /* while there are attribute names    */
  6494.          VioWrtTTY(pdena1->szName, (USHORT) pdena1->cbName, 0L);
  6495.          VioWrtTTY("\r\n", 2, 0L);
  6496.          offset += sizeof(DENA1) + pdena1->cbName;
  6497.          pdena1 = MAKEP(sel, offset);           /* points to next name */
  6498.      }
  6499.  }
  6500.  
  6501.  
  6502.  
  6503.  
  6504.  
  6505.  
  6506.  
  6507.  █    DosExitCritSec
  6508.  ────────────────────────────────────────────────────────────────────────────
  6509.  
  6510.  USHORT DosExitCritSec  (VOID)
  6511.  
  6512.  
  6513.  
  6514.  The DosExitCritSec function restores execution of all threads suspended by
  6515.  the DosEnterCritSec function.
  6516.  
  6517.  This function has no parameters.
  6518.  
  6519.  
  6520.  Return Value
  6521.  
  6522.  The return value is zero if the function is successful. Otherwise, it is an
  6523.  error value, which may be the following:
  6524.  
  6525.       ERROR_CRITSEC_UNDERFLOW
  6526.  
  6527.  
  6528.  
  6529.  
  6530.  
  6531.  Comments
  6532.  
  6533.  MS OS/2 maintains the number of outstanding DosEnterCritSec requests. This
  6534.  count is incremented by DosEnterCritSec requests and decremented by
  6535.  DosExitCritSec requests. If the count is greater than zero, a DosExitCritSec
  6536.  request will not restore normal thread execution. If the count is less than
  6537.  zero, the ERROR_CRITSEC_UNDERFLOW will be returned.
  6538.  
  6539.  
  6540.  See Also
  6541.  
  6542.  DosCreateThread, DosEnterCritSec
  6543.  
  6544.  
  6545.  Changes
  6546.  
  6547.  DosExitCritSec now returns an error value if it is called without a
  6548.  corresponding call to DosEnterCritSec.
  6549.  
  6550.  
  6551.  █    DosExitList
  6552.  ────────────────────────────────────────────────────────────────────────────
  6553.  
  6554.  USHORT DosExitList  (fFnCode, pfnFunction)
  6555.  
  6556.  USHORT  fFnCode;                  /*function code */
  6557.  
  6558.  PFNEXITLIST                       /*pointer to address of function */
  6559.  pfnFunction(USHORT);
  6560.  
  6561.  
  6562.  The DosExitList function specifies a function that is executed when the
  6563.  current process ends. This "termination function" can define additional
  6564.  termination functions. The DosExitList function can be called one or more
  6565.  times: each call adds or subtracts a function from an internal list
  6566.  maintained by the system. When the current process terminates, MS OS/2
  6567.  transfers control to each function in the list.
  6568.  
  6569.  
  6570.  Parameters
  6571.  
  6572.  fFnCode  Specifies whether a function's address is added to or removed from
  6573.  the list. If the function is added, the high byte of this parameter
  6574.  specifies the order in which the function should be called. The exit-list
  6575.  routines with a low-order high byte will be called before those with a
  6576.  high-order high byte. The low byte of this parameter can be one of the
  6577.  following values:
  6578.  
  6579.  Value                             Meaning
  6580.  ────────────────────────────────────────────────────────────────────────────
  6581.  
  6582.  EXLST_ADD                         Adds the function to the termination
  6583.                                    list. If this flag is specified, the
  6584.                                    high byte of the parameter specifies the
  6585.                                    order in which the function is called.
  6586.                                    It can be a value from 0 through 255. A
  6587.                                    value of 0 specifies that this function
  6588.                                    is to be called first. In the event of
  6589.                                    duplicate order numbers, the last
  6590.                                    function added with the duplicate order
  6591.                                    number is called before the first
  6592.                                    function added with the duplicate order
  6593.                                    number.
  6594.  
  6595.  EXLST_EXIT                        Termination processing is complete.
  6596.                                    Calls the next function on the
  6597.                                    termination list.
  6598.  
  6599.  EXLST_REMOVE                      Removes the function from the
  6600.                                    termination list.
  6601.  
  6602.  
  6603.  
  6604.  pfnFunction  Points to the termination function to be added to the list. For
  6605.  a full description, see the following "Comments" section.
  6606.  
  6607.  
  6608.  Return Value
  6609.  
  6610.  The return value is zero if the function is successful. Otherwise, it is an
  6611.  error value, which may be one of the following:
  6612.  
  6613.       ERROR_INVALID_DATA
  6614.       ERROR_NOT_ENOUGH_MEMORY
  6615.  
  6616.  
  6617.  
  6618.  
  6619.  
  6620.  Comments
  6621.  
  6622.  When adding an exit-list function, it is important that the exit-list
  6623.  function not call any system functions with a lower exit-list order. The
  6624.  order is determined by the high-byte of the fFnCode parameter. The list on
  6625.  the following page defines the orders of the various system components:
  6626.  
  6627.  Order                             Component
  6628.  ────────────────────────────────────────────────────────────────────────────
  6629.  
  6630.  0x80-0x88                         Extended Edition Database Manager
  6631.  
  6632.  0x90-0x98                         Extended Edition Communication Manager
  6633.  
  6634.  0xA0-0xA8                         Presentation Manager
  6635.  
  6636.  0xB0                              KBD component
  6637.  
  6638.  0xC0                              VIO component
  6639.  
  6640.  0xD0                              IPC Queues component
  6641.  
  6642.  
  6643.  
  6644.  Dynamic-link-library modules often use the DosExitList function. It allows
  6645.  dynamic-link-library modules to free resources or clear flags and semaphores
  6646.  if the client process terminates without notifying them.
  6647.  
  6648.  The termination function has one parameter and no return value. The function
  6649.  should have the following form:
  6650.  
  6651.  VOID PASCAL FAR FuncName(usTermCode)
  6652.  USHORT usTermCode;
  6653.  {
  6654.      .
  6655.      .
  6656.      .
  6657.      DosExitList(EXLST_EXIT, (PFNEXITLIST) NULL);
  6658.  }
  6659.  
  6660.  
  6661.  
  6662.  
  6663.  The usTermCode parameter of the termination function specifies the reason
  6664.  the process ended. This parameter can be one of the following values:
  6665.  
  6666.  Value                             Meaning
  6667.  ────────────────────────────────────────────────────────────────────────────
  6668.  
  6669.  TC_EXIT                           Normal exit
  6670.  
  6671.  TC_HARDERROR                      Hard-error abort
  6672.  
  6673.  TC_KILLPROCESS                    Unintercepted DosKillProcess
  6674.  
  6675.  TC_TRAP                           Trap operation
  6676.  
  6677.  
  6678.  
  6679.  Before transferring control to the termination function, MS OS/2 resets the
  6680.  stack to its initial value. MS OS/2 then passes control to the function by
  6681.  using a jmp instruction. The termination function should carry out its tasks
  6682.  and then call the DosExitList function with the fFnCode parameter set to
  6683.  EXLST_EXIT. This parameter setting directs the system to call the next
  6684.  function on the termination list. When all functions on the list have been
  6685.  called, the process ends.
  6686.  
  6687.  Termination functions should be as short and fail-safe as possible. Before
  6688.  the termination functions are executed, all threads except for the one
  6689.  executing the DosExitList function are destroyed. Note that a termination
  6690.  function must call the DosExitList function to end; otherwise, the process
  6691.  "hangs" because MS OS/2 cannot terminate it.
  6692.  
  6693.  A termination function can call most MS OS/2 system functions; however, it
  6694.  must not call the DosCreateThread or DosExecPgm function.
  6695.  
  6696.  
  6697.  Example
  6698.  
  6699.  This example calls DosExitList, which then adds the locally defined function
  6700.  CleanUp to the list of routines to be called when the process terminates.
  6701.  The CleanUp function displays a message that it is cleaning up, and then
  6702.  calls DosExitList, reporting that it has finished and that the next function
  6703.  on the termination list can be called.
  6704.  
  6705.      /* Add the function, and have it be called last. */
  6706.  
  6707.      DosExitList(EXLST_ADD | 0xFF00, CleanUp);
  6708.      .
  6709.      .
  6710.      .
  6711.      DosExit(EXIT_PROCESS, 0);
  6712.  }
  6713.  
  6714.  VOID PASCAL FAR CleanUp(usTermCode)
  6715.  USHORT usTermCode;
  6716.  {
  6717.      VioWrtTTY("Cleaning up...\r\n", 16, 0);
  6718.      .
  6719.      .
  6720.      .
  6721.      DosExitList(EXLST_EXIT,     /* termination complete */
  6722.          (PFNEXITLIST) NULL);
  6723.  }
  6724.  
  6725.  
  6726.  
  6727.  
  6728.  
  6729.  See Also
  6730.  
  6731.  DosCreateThread, DosExecPgm, DosExit, DosKillProcess
  6732.  
  6733.  
  6734.  Corrections
  6735.  
  6736.  When the EXLST_ADD constant is used in the fFnCode parameter, the high byte
  6737.  of the parameter contains an order number (0 through 255). You can use this
  6738.  number to specify the order in which your exit-list function is called.
  6739.  
  6740.  The function template in the example incorrectly listed the prototype of the
  6741.  termination function as PFNEXITLIST. It should be VOID PASCAL FAR.
  6742.  
  6743.  
  6744.  █    DosFileIO
  6745.  ────────────────────────────────────────────────────────────────────────────
  6746.  
  6747.  USHORT DosFileIO  (hf, pbCmd, cbCmd, pusErr)
  6748.  
  6749.  HFILE  hf;                        /*file handle */
  6750.  
  6751.  PBYTE  pbCmd;                     /*pointer to buffer for commands */
  6752.  
  6753.  USHORT  cbCmd;                    /*length of command buffer */
  6754.  
  6755.  PUSHORT  pusErr;                  /*pointer to error offset */
  6756.  
  6757.  
  6758.  The DosFileIO function performs multiple lock, unlock, seek, read, and write
  6759.  operations on a file.
  6760.  
  6761.  
  6762.  Parameters
  6763.  
  6764.  hf  Identifies the file on which to perform the commands. This handle must
  6765.  have been created previously by using the DosOpen function.
  6766.  
  6767.  pbCmd  Points to the buffer that contains one or more of the following
  6768.  structures: FIOLOCKCMD, FIOLOCKREC, FIOUNLOCKCMD, FIOUNLOCKREC, FIOSEEKCMD,
  6769.  or FIOREADWRITE. The structures have the following forms:
  6770.  
  6771.  typedef struct  _FIOLOCKCMD {
  6772.      USHORT usCmd;
  6773.      USHORT cLockCnt;
  6774.      ULONG  cTimeOut;
  6775.  } FIOLOCKCMD;
  6776.  
  6777.  
  6778.  
  6779.  typedef struct  _FIOLOCKREC {
  6780.      USHORT fShare;
  6781.      ULONG  cbStart;
  6782.      ULONG  cbLength;
  6783.  } FIOLOCKREC;
  6784.  
  6785.  
  6786.  
  6787.  typedef struct  _FIOUNLOCKCMD {
  6788.      USHORT usCmd;
  6789.      USHORT cUnlockCnt;
  6790.  } FIOUNLOCKCMD;
  6791.  
  6792.  
  6793.  
  6794.  typedef struct  _FIOUNLOCKREC {
  6795.      ULONG cbStart;
  6796.      ULONG cbLength;
  6797.  } FIOUNLOCKREC;
  6798.  
  6799.  
  6800.  
  6801.  typedef struct  _FIOSEEKCMD {
  6802.      USHORT usCmd;
  6803.      USHORT fsMethod;
  6804.      ULONG  cbDistance;
  6805.      ULONG  cbNewPosition;
  6806.  } FIOSEEKCMD;
  6807.  
  6808.  
  6809.  
  6810.  typedef struct  _FIOREADWRITE {
  6811.      USHORT usCmd;
  6812.      PVOID  pbBuffer;
  6813.      USHORT cbBufferLen;
  6814.      USHORT cbActualLen;
  6815.  } FIOREADWRITE;
  6816.  
  6817.  
  6818.  
  6819.  
  6820.  For a full description, see Chapter 4, "Types, Macros, Structures."
  6821.  
  6822.  cbCmd  Specifies the length (in bytes) of the pbCmd parameter.
  6823.  
  6824.  pusErr  Points to a variable that receives the byte offset of the structure
  6825.  that caused an error. The offset is relative to the beginning of the buffer
  6826.  pointed to by the pbCmd parameter.
  6827.  
  6828.  
  6829.  Return Value
  6830.  
  6831.  The return value is zero if the function is successful. Otherwise, it is an
  6832.  error value, which may be one of the following:
  6833.  
  6834.       ERROR_ACCESS_DENIED
  6835.       ERROR_DIRECT_ACCESS_HANDLE
  6836.       ERROR_INTERRUPT
  6837.       ERROR_INVALID_HANDLE
  6838.       ERROR_INVALID_PARAMETER
  6839.       ERROR_LOCK_VIOLATION
  6840.       ERROR_NEGATIVE_SEEK
  6841.       ERROR_SEEK_ON_DEVICE
  6842.       ERROR_SHARING_BUFFER_EXCEEDED
  6843.  
  6844.  
  6845.  
  6846.  
  6847.  
  6848.  Comments
  6849.  
  6850.  The DosFileIO function allows you to combine the following operations into a
  6851.  single function call:
  6852.  
  6853.    ■   Locking and unlocking multiple file ranges
  6854.  
  6855.    ■   Changing the file-position pointer
  6856.  
  6857.    ■   Reading and/or writing
  6858.  
  6859.  
  6860.  
  6861.  
  6862.  Combining these operations into one call can improve system performance,
  6863.  particularly in a networking environment.
  6864.  
  6865.  The DosFileIO function provides a simple mechanism for denying other
  6866.  processes read/write or write access to regions of the file. If another
  6867.  process attempts to read from or write to a no-access region, or attempts to
  6868.  write in a read-only region, an error is returned. If a time-out occurs
  6869.  before the locking operation is complete, DosFileIO returns an error to the
  6870.  calling process.
  6871.  
  6872.  Since the calling process may return after the time-out period has expired
  6873.  without receiving an ERROR_SEM_TIMEOUT message, semaphore time-out values
  6874.  should not be used for exact timing or for determining the sequence of I/O
  6875.  operations.
  6876.  
  6877.  Before a range is locked, it must be cleared of any locked subranges or
  6878.  locked overlapping ranges.
  6879.  
  6880.  Each I/O operation completes before the next one begins. The operations
  6881.  continue until all are complete or until one fails.
  6882.  
  6883.  
  6884.  Example
  6885.  
  6886.  This example opens the file abc.txt, allocates memory for the command
  6887.  buffer, initializes the commands in that buffer, and calls DosFileIO to move
  6888.  the file 10 bytes into the file and then read from the file:
  6889.  
  6890.  HFILE hf;
  6891.  USHORT usAction;
  6892.  SEL sel;
  6893.  BYTE abBuf[512];
  6894.  LONG lError;
  6895.  
  6896.  PFIOREADWRITE pfiorw;
  6897.  PFIOSEEKCMD pfioseek;
  6898.  
  6899.  DosOpen("abc.txt", &hf, &usAction, 0L, FILE_NORMAL, FILE_OPEN,
  6900.      OPEN_ACCESS_READONLY | OPEN_SHARE_DENYNONE, 0L);
  6901.  DosAllocSeg(sizeof(FIOSEEKCMD) + sizeof(FIOREADWRITE), &sel, SEG_NONSHARED);
  6902.  
  6903.  pfioseek = MAKEP(sel, 0);
  6904.  pfioseek->usCmd = FIO_SEEK;
  6905.  pfioseek->fsMethod = FILE_BEGIN;
  6906.  pfioseek->cbDistance = 10L;
  6907.  
  6908.  pfiorw = MAKEP(sel, sizeof(FIOSEEKCMD));
  6909.  pfiorw->usCmd = FIO_READ;
  6910.  pfiorw->pbBuffer = (PVOID) abBuf;
  6911.  pfiorw->cbBufferLen = sizeof(abBuf);
  6912.  
  6913.  DosFileIO(hf,                                    /* file handle    */
  6914.      MAKEP(sel, 0),                               /* buffer address */
  6915.      (sizeof(FIOSEEKCMD) + sizeof(FIOREADWRITE)), /* buffer size    */
  6916.      &lError);                         /* address of error variable */
  6917.  
  6918.  
  6919.  
  6920.  
  6921.  
  6922.  See Also
  6923.  
  6924.  DosChgFilePtr, DosFileLocks, DosOpen, DosRead, DosWrite
  6925.  
  6926.  
  6927.  █    DosFindFirst2
  6928.  ────────────────────────────────────────────────────────────────────────────
  6929.  
  6930.  USHORT DosFindFirst2  (pszFileName, phDir, usAttribute, pBuf, cbBuf,
  6931.  pusSearchCount, usInfoLevel, ulReserved)
  6932.  
  6933.  PSZ  pszFileName;                 /*pointer to filename */
  6934.  
  6935.  PHDIR  phDir;                     /*pointer to directory handle */
  6936.  
  6937.  USHORT  usAttribute;              /*attributes of file to be found */
  6938.  
  6939.  PVOID  pBuf;                      /*pointer to buffer for results */
  6940.  
  6941.  USHORT  cbBuf;                    /*size of results buffer */
  6942.  
  6943.  PUSHORT  pusSearchCount;          /*number of entries found */
  6944.  
  6945.  USHORT  usInfoLevel;              /*level of information to retrieve */
  6946.  
  6947.  ULONG  ulReserved;                /*must be zero */
  6948.  
  6949.  
  6950.  The DosFindFirst2 function searches a directory for the file or files whose
  6951.  filename and attributes match the specified filename and attributes.
  6952.  
  6953.  The DosFindFirst2 function is a family API function.
  6954.  
  6955.  
  6956.  Parameters
  6957.  
  6958.  pszFileName  Points to a null-terminated string. This string must be a valid
  6959.  MS OS/2 path and can contain wildcard characters.
  6960.  
  6961.  phDir  Points to the variable that contains the handle of the directory to
  6962.  search.
  6963.  
  6964.  usAttribute  Specifies the file attribute(s) of the file to be located. This
  6965.  parameter can be a combination of the following values:
  6966.  
  6967.  Value                             Meaning
  6968.  ────────────────────────────────────────────────────────────────────────────
  6969.  
  6970.  FILE_NORMAL                       Search for normal files.
  6971.  
  6972.  FILE_READONLY                     Search for read-only files.
  6973.  
  6974.  FILE_HIDDEN                       Search for hidden files.
  6975.  
  6976.  FILE_SYSTEM                       Search for system files.
  6977.  
  6978.  FILE_DIRECTORY                    Search for subdirectories.
  6979.  
  6980.  FILE_ARCHIVED                     Search for archived files.
  6981.  
  6982.  
  6983.  
  6984.  pBuf  Points to the buffer in which the file information is returned. The
  6985.  format for this buffer is determined by the value specified in the
  6986.  usInfoLevel parameter.
  6987.  
  6988.  cbBuf  Specifies the size (in bytes) of the buffer pointed to by pBuf.
  6989.  
  6990.  pusSearchCount  Points to the variable that specifies the number of matching
  6991.  entries to locate. The DosFindFirst2 function copies the number of entries
  6992.  found to this parameter before returning.
  6993.  
  6994.  usInfoLevel  Specifies the type of file information to retrieve. This
  6995.  parameter can be one of the following values:
  6996.  
  6997.  Value                             Meaning
  6998.  ────────────────────────────────────────────────────────────────────────────
  6999.  
  7000.  FIL_STANDARD                      Return a FILEFINDBUF structure with the
  7001.                                    results of the search. The information
  7002.                                    returned is identical to that returned
  7003.                                    by the DosFindFirst function.
  7004.  
  7005.  FIL_QUERYEASIZE                   Return a FILEFINDBUF2 structure with the
  7006.                                    results of the search, and that contains
  7007.                                    the size of the buffer needed to
  7008.                                    retrieve the extended attributes.
  7009.  
  7010.  FIL_QUERYEASFROMLIST              Return a buffer that contains both the
  7011.                                    file information and the extended
  7012.                                    attributes for the file.
  7013.  
  7014.  
  7015.  
  7016.  The FILEFINDBUF structure has the following form:
  7017.  
  7018.  typedef struct _FILEFINDBUF {
  7019.      FDATE  fdateCreation;
  7020.      FTIME  ftimeCreation;
  7021.      FDATE  fdateLastAccess;
  7022.      FTIME  ftimeLastAccess;
  7023.      FDATE  fdateLastWrite;
  7024.      FTIME  ftimeLastWrite;
  7025.      ULONG  cbFile;
  7026.      ULONG  cbFileAlloc;
  7027.      USHORT attrFile;
  7028.      UCHAR  cchName;
  7029.      CHAR   achName[13];
  7030.  } FILEFINDBUF;
  7031.  
  7032.  
  7033.  
  7034.  
  7035.  The FILEFINDBUF2 structure has the following form:
  7036.  
  7037.  typedef struct _FILEFINDBUF2 {
  7038.      FDATE  fdateCreation;
  7039.      FTIME  ftimeCreation;
  7040.      FDATE  fdateLastAccess;
  7041.      FTIME  ftimeLastAccess;
  7042.      FDATE  fdateLastWrite;
  7043.      FTIME  ftimeLastWrite;
  7044.      ULONG  cbFile;
  7045.      ULONG  cbFileAlloc;
  7046.      USHORT attrFile;
  7047.      USHORT cbList;
  7048.      UCHAR  cchName;
  7049.      CHAR   achName[13];
  7050.  } FILEFINDBUF2;
  7051.  
  7052.  
  7053.  
  7054.  
  7055.  For a full description, see Chapter 4, "Types, Macros, Structures."
  7056.  
  7057.  ulReserved  Specifies a reserved value; must be zero.
  7058.  
  7059.  
  7060.  Return Value
  7061.  
  7062.  The return value is zero if the function is successful. Otherwise, it is an
  7063.  error value, which may be one of the following:
  7064.  
  7065.      ERROR_BUFFER_OVERFLOW
  7066.      ERROR_EAS_DIDNT_FIT
  7067.      ERROR_EA_LIST_INCONSISTENT
  7068.      ERROR_FILENAME_EXCED_RANGE
  7069.      ERROR_INVALID_EA_NAME
  7070.      ERROR_INVALID_HANDLE
  7071.      ERROR_INVALID_PARAMETER
  7072.      ERROR_META_EXPANSION_TOO_LONG
  7073.      ERROR_NO_MORE_FILES
  7074.      ERROR_NO_MORE_SEARCH_HANDLES
  7075.      ERROR_PATH_NOT_FOUND
  7076.  
  7077.  
  7078.  
  7079.  
  7080.  
  7081.  Comments
  7082.  
  7083.  The DosFindNext function uses the directory handle pointed to by the phDir
  7084.  parameter of the DosFindFirst2 function to repeat the search. If
  7085.  DosFindFirst2 returns an error value other than ERROR_EAS_DIDNT_FIT, no
  7086.  directory handle is allocated.
  7087.  
  7088.  If the phDir parameter is HDIR_SYSTEM, the system-default search-directory
  7089.  handle is used; any previous search that used HDIR_SYSTEM terminates if this
  7090.  parameter is HDIR_CREATE, the search directory used by the process is
  7091.  created, and the function copies the handle of this search directory to the
  7092.  variable pointed to by the phDir parameter. If the handle was created by a
  7093.  previous call to DosFindFirst, it can be used in subsequent calls to
  7094.  DosFindNext.
  7095.  
  7096.  If the value of the usInfoLevel parameter is FILE_QUERYEASIZE, the cbList
  7097.  field of the FILEFINDBUF2 structure can be used to calculate the size of the
  7098.  buffer necessary for a FILE_QUERYEASFROMLIST information request. For MS
  7099.  OS/2 versions 1.2 and later, the value of cbList will never exceed 65,535.
  7100.  
  7101.  To use a FILE_QUERYEASFROMLIST information request, you must supply a buffer
  7102.  large enough for an EAOP structure and a FILEFINDBUF structure, plus enough
  7103.  space for the extended attributes. You must initialize the first portion of
  7104.  this buffer as an EAOP structure, and fill in the GEALIST structure with the
  7105.  extended-attribute names to retrieve. On return, the EAOP structure will be
  7106.  unchanged. It will be followed immediately by a FILEFINDBUF2 structure,
  7107.  without the last three fields. This is followed by an FEALIST structure (the
  7108.  address is the same as the cbList field of the FILEFINDBUF2 structure). The
  7109.  FEALIST structure is in turn followed by a single byte that specifies the
  7110.  length of the filename, and that is followed by a null-terminated string
  7111.  that specifies the filename. For an example of how to use structure pointers
  7112.  to access each of these fields, see the "Example" section.
  7113.  
  7114.  If there is not enough room in the output buffer to hold the
  7115.  extended-attribute information, the error ERROR_EAS_DIDNT_FIT is returned.
  7116.  The search handle will be allocated, however, and can be used in subsequent
  7117.  calls to the DosFindNext function. If no extended attribute is found, the
  7118.  FEA structure for that extended attribute will contain the name of the
  7119.  attribute, but the cbValue field will be zero.
  7120.  
  7121.  
  7122.  Example
  7123.  
  7124.  This example shows how to set up pointers to access the various fields of
  7125.  the buffer returned by a FIL_QUERYEASFROMLIST level request:
  7126.  
  7127.  /* Declare a structure to retrieve the .TYPE attribute name. */
  7128.  
  7129.  typedef struct _TYPEATTR {
  7130.      ULONG cbList;
  7131.      BYTE  cbName;
  7132.      CHAR  szName[6];
  7133.  } TYPEATTR;
  7134.  
  7135.  #define BUFSIZE 2 * 1024              /* default buffer size         */
  7136.  
  7137.  SEL sel;                              /* selector for buffer         */
  7138.  HDIR hdir = HDIR_CREATE;              /* directory handle            */
  7139.  USHORT usSearchCount = 1;             /* number of files to retrieve */
  7140.  TYPEATTR typeattr;                    /* TYPE attribute structure    */
  7141.  PEAOP peaop;
  7142.  PFILEFINDBUF2 pfindbuf2;
  7143.  PFEALIST pfeal;
  7144.  PSZ pszFileName;
  7145.  PUCHAR pcchFileName;
  7146.  
  7147.  DosAllocSeg(BUFSIZE, &sel, SEG_NONSHARED);  /* creates buffer        */
  7148.  peaop = MAKEP(sel, 0);                      /* sets up peaop pointer */
  7149.  
  7150.  typeattr.cbList = sizeof(TYPEATTR);         /* structure size        */
  7151.  strcpy(typeattr.szName, ".TYPE");           /* EA name               */
  7152.  typeattr.cbName = sizeof(typeattr.szName) - 1; /* name length        */
  7153.  
  7154.  peaop->fpGEAList = (PGEALIST) &typeattr;   /* size of GEALIST struc. */
  7155.  
  7156.  if (!DosFindFirst2("eafile", &hdir, FILE_NORMAL,
  7157.          peaop, BUFSIZE,
  7158.          &usSearchCount, FIL_QUERYEASFROMLIST, 0L)) {
  7159.      pfindbuf2 = MAKEP(sel, sizeof(EAOP));   /* FILEFINDBUF structure */
  7160.      pfeal = (PFEALIST) &pfindbuf2->cbList;  /* FEALIST structure     */
  7161.      pcchFileName = ((PSZ) pfeal) + pfeal->cbList; /* filename length */
  7162.      pszFileName = pcchFileName + 1;               /* filename        */
  7163.  }
  7164.  
  7165.  
  7166.  
  7167.  
  7168.  
  7169.  See Also
  7170.  
  7171.  DosFindClose, DosFindFirst, DosFindNext, DosQFileMode, DosQFSInfo
  7172.  
  7173.  
  7174.  █    DosFindNext
  7175.  ────────────────────────────────────────────────────────────────────────────
  7176.  
  7177.  USHORT DosFindNext  (hdir, pfindbuf, cbfindbuf, pcSearch)
  7178.  
  7179.  HDIR  hdir;                       /*handle of search directory */
  7180.  
  7181.  PFILEFINDBUF  pfindbuf;           /*pointer to structure for search result
  7182.                                    */
  7183.  
  7184.  USHORT  cbfindbuf;                /*length of result buffer */
  7185.  
  7186.  PUSHORT  pcSearch;                /*pointer to variable for file count */
  7187.  
  7188.  
  7189.  The DosFindNext function searches for the next file or group of files
  7190.  matching the specified filename and attributes. The function copies the name
  7191.  and requested information about the file to the specified structure. The
  7192.  information returned is as accurate as the most recent call to the DosClose
  7193.  or DosBufReset function.
  7194.  
  7195.  The DosFindNext function is a family API function.
  7196.  
  7197.  
  7198.  Parameters
  7199.  
  7200.  hdir  Identifies the search directory and the filename(s) to search for.
  7201.  This handle must have been created previously by using the DosFindFirst
  7202.  function.
  7203.  
  7204.  pfindbuf  Points to the structure that receives the result of the search.
  7205.  This structure will be either a FILEFINDBUF or FILEFINDBUF2 structure,
  7206.  depending on the information level requested in the DosFindFirst or
  7207.  DosFindFirst2 function that preceded this function. For specific information
  7208.  on the format of these structures, see the DosFindFirst and DosFindFirst2
  7209.  functions.
  7210.  
  7211.  cbfindbuf  Specifies the length (in bytes) of the structure pointed to by
  7212.  the pfindbuf parameter.
  7213.  
  7214.  pcSearch  Points to the variable that specifies the number of matching
  7215.  filenames to locate. The function copies the number of filenames found to
  7216.  the variable before returning.
  7217.  
  7218.  
  7219.  Return Value
  7220.  
  7221.  The return value is zero if the function is successful. Otherwise, it is an
  7222.  error value, which may be one of the following:
  7223.  
  7224.       ERROR_BUFFER_OVERFLOW
  7225.       ERROR_INVALID_HANDLE
  7226.       ERROR_INVALID_PARAMETER
  7227.       ERROR_NO_MORE_FILES
  7228.       ERROR_NOT_DOS_DISK
  7229.       ERROR_EAS_DIDNT_FIT
  7230.  
  7231.  
  7232.  
  7233.  
  7234.  
  7235.  Comments
  7236.  
  7237.  The pcSearch parameter specifies the number of files to search for. The
  7238.  number of files whose information is copied is the number of files
  7239.  requested, the number of files whose information fits in the structure, or
  7240.  the number of files that exist, whichever is smallest. If you want to obtain
  7241.  information for more than one file, the pfindbuf parameter must point to a
  7242.  buffer that consists of consecutive structures. If the DosFindNext function
  7243.  fails to find a match or cannot copy all the information about the file to
  7244.  the structure, it returns an error.
  7245.  
  7246.  
  7247.  Restrictions
  7248.  
  7249.  In real mode, the following restriction applies to the DosFindNext function:
  7250.  
  7251.  
  7252.    ■   The hdir parameter must be set to HDIR_SYSTEM.
  7253.  
  7254.  
  7255.  
  7256.  
  7257.  Example
  7258.  
  7259.  This example calls the DosFindFirst function to find all files matching
  7260.  "*.*", and then uses the DosFindNext function to display them one at a time:
  7261.  
  7262.  
  7263.  FILEFINDBUF findbuf;
  7264.  HDIR hdir = HDIR_CREATE;
  7265.  USHORT cSearch = 1;
  7266.  DosFindFirst("*.*", &hdir, FILE_NORMAL, &findbuf, sizeof(findbuf),
  7267.      &cSearch, 0L);
  7268.  do {
  7269.      VioWrtTTY(findbuf.achName, findbuf.cchName, 0);
  7270.      VioWrtTTY("\r\n", 2, 0);     /* cursor to next line     */
  7271.  }
  7272.  while (DosFindNext(hdir,         /* handle of directory     */
  7273.      &findbuf,                    /* address of buffer       */
  7274.      sizeof(findbuf),             /* length of buffer        */
  7275.      &cSearch)                    /* number of files to find */
  7276.      == 0);                       /* while no error occurs   */
  7277.  
  7278.  
  7279.  
  7280.  
  7281.  
  7282.  See Also
  7283.  
  7284.  DosBufReset, DosClose, DosFindClose, DosFindFirst, DosFindFirst2
  7285.  
  7286.  
  7287.  Changes
  7288.  
  7289.  DosFindNext returns the same type of structure as requested by the most
  7290.  recent call to either DosFindFirst or DosFindFirst2.
  7291.  
  7292.  
  7293.  █    DosFreeResource
  7294.  ────────────────────────────────────────────────────────────────────────────
  7295.  
  7296.  USHORT DosFreeResource  (pvData)
  7297.  
  7298.  PVOID  pvData;                    /*pointer to data to free */
  7299.  
  7300.  
  7301.  
  7302.  
  7303.  The DosFreeResource function frees memory allocated by a previous call to
  7304.  the DosGetResource2 function.
  7305.  
  7306.  
  7307.  Parameters
  7308.  
  7309.  pvData  Points to the buffer to free. This pointer should have been returned
  7310.  by a previous call to the DosGetResource2 function.
  7311.  
  7312.  
  7313.  Return Value
  7314.  
  7315.  The return value is zero if the function is successful. Otherwise, it is an
  7316.  error value.
  7317.  
  7318.  
  7319.  See Also
  7320.  
  7321.  DosGetResource, DosGetResource2
  7322.  
  7323.  
  7324.  █    DosFreeSeg
  7325.  ────────────────────────────────────────────────────────────────────────────
  7326.  
  7327.  USHORT DosFreeSeg  (sel)
  7328.  
  7329.  SEL  sel;                         /*segment selector */
  7330.  
  7331.  
  7332.  The DosFreeSeg function frees the specified memory segment. This function
  7333.  accepts selectors for memory segments, shared-memory segments, hugememory
  7334.  segments, aliased code segments, and resource segments allocated by
  7335.  DosGetResource. DosFreeSeg frees a shared-memory segment after the segment
  7336.  is freed by the last process accessing it. DosFreeSeg frees the code-segment
  7337.  selector for aliased code segments, but the corresponding data-segment
  7338.  selector remains valid until it is freed.
  7339.  
  7340.  The DosFreeSeg function is a family API function.
  7341.  
  7342.  
  7343.  Parameters
  7344.  
  7345.  sel  Specifies the segment to free.
  7346.  
  7347.  
  7348.  Return Value
  7349.  
  7350.  The return value is zero if the function is successful. Otherwise, it is an
  7351.  error value, which may be the following:
  7352.  
  7353.       ERROR_ACCESS_DENIED
  7354.  
  7355.  
  7356.  
  7357.  
  7358.  
  7359.  Comments
  7360.  
  7361.  DosFreeSeg can be issued from ring 2, but the segment to free must be a
  7362.  ring-3 segment.
  7363.  
  7364.  DosFreeSeg should not be used to free resource segments allocated by the
  7365.  DosGetResource2 function. To free those segments, use the DosFreeResource
  7366.  function.
  7367.  
  7368.  
  7369.  Restrictions
  7370.  
  7371.  In real mode, the following restriction applies to the DosFreeSeg function:
  7372.  
  7373.    ■   A code-segment selector (created by using the DosCreateCSAlias
  7374.        function) and the corresponding data-segment selector are the same.
  7375.        Freeing one frees both.
  7376.  
  7377.  
  7378.  
  7379.  
  7380.  Example
  7381.  
  7382.  This example allocates three segments of memory, then calls the DosFreeSeg
  7383.  function to free the memory:
  7384.  
  7385.  SEL sel;
  7386.  DosAllocHuge(3, 200, &sel, 5, SEG_NONSHARED);
  7387.      .
  7388.      .
  7389.      .
  7390.  DosFreeSeg(sel);
  7391.  
  7392.  
  7393.  
  7394.  
  7395.  
  7396.  See Also
  7397.  
  7398.  DosAllocHuge, DosAllocSeg, DosAllocShrSeg, DosCreateCSAlias,
  7399.  DosFreeResource, DosGetResource, DosGetResource2
  7400.  
  7401.  
  7402.  Changes
  7403.  
  7404.  DosFreeSeg should not be used to free segments allocated by the
  7405.  DosGetResource2 function.
  7406.  
  7407.  
  7408.  █    DosFSAttach
  7409.  ────────────────────────────────────────────────────────────────────────────
  7410.  
  7411.  USHORT DosFSAttach  (pszDevName, pszFSD, pData, cbData, fsOp, ulReserved)
  7412.  
  7413.  PSZ  pszDevName;                  /*pointer to the device name */
  7414.  
  7415.  PSZ  pszFSD;                      /*pointer to the file system */
  7416.  
  7417.  PBYTE  pData;                     /*pointer to the buffer for file-system
  7418.                                    arguments */
  7419.  
  7420.  USHORT  cbData;                   /*length of the argument buffer */
  7421.  
  7422.  USHORT  fsOp;                     /*attach or the detach connection */
  7423.  
  7424.  ULONG  ulReserved;                /*must be zero */
  7425.  
  7426.  
  7427.  The DosFSAttach function attaches or detaches a drive or pseudo-character
  7428.  device from a remote file system.
  7429.  
  7430.  
  7431.  Parameters
  7432.  
  7433.  pszDevName  Points to a null-terminated string that specifies the drive
  7434.  letter followed by a colon or a pseudo-character device name. If this
  7435.  parameter is a pseudo-character device name, the format of the string is
  7436.  \edevice\efilename, where filename is a valid MS OS/2 filename.
  7437.  
  7438.  pszFSD  Points to a null-terminated string that specifies the name of the
  7439.  remote file system to attach to or detach from the device specified by the
  7440.  pszDevName parameter.
  7441.  
  7442.  pData  Points to a buffer that contains the file-system arguments. The
  7443.  meaning of the arguments is specific to the file system. The first word of
  7444.  the buffer specifies the number of strings it contains; the rest of the
  7445.  buffer contains contiguous strings.
  7446.  
  7447.  cbData  Specifies the length (in bytes) of the data pointed to by the pData
  7448.  parameter.
  7449.  
  7450.  fsOp  Specifies the type of operation to perform. A value of FS_ATTACH
  7451.  attaches a file-system connection. A value of FS_DETACH detaches a
  7452.  file-system connection.
  7453.  
  7454.  ulReserved  Specifies a reserved value; must be zero.
  7455.  
  7456.  
  7457.  Return Value
  7458.  
  7459.  The return value is zero if the function is successful. Otherwise, it is an
  7460.  error value, which may be one of the following:
  7461.  
  7462.       ERROR_ALREADY_ASSIGNED
  7463.       ERROR_INVALID_DRIVE
  7464.       ERROR_INVALID_FSD_NAME
  7465.       ERROR_INVALID_LEVEL
  7466.       ERROR_INVALID_PATH
  7467.       ERROR_NOT_ENOUGH_MEMORY
  7468.  
  7469.  
  7470.  
  7471.  
  7472.  
  7473.  Comments
  7474.  
  7475.  Drive letters that represent local drives cannot be redirected.
  7476.  
  7477.  When a drive is attached to a file system, all requests to that drive are
  7478.  routed to the file system. When a drive is detached from a file system, the
  7479.  drive name can no longer be used.
  7480.  
  7481.  When a pseudo-character device name is attached to a file system, all
  7482.  requests to that name are routed to the file system. When a pseudo-character
  7483.  device is detached from a file system, the device name can no longer be used
  7484.  unless it overlaid the name of an existing device; in this case, the
  7485.  previous device regains control.
  7486.  
  7487.  
  7488.  Example
  7489.  
  7490.  This example calls DosFSAttach to attach a LAN server to drive X, then calls
  7491.  DosFSAttach again to detach the LAN server:
  7492.  
  7493.  CHAR szShareName[] = { 1, 0,        /* number of strings              */
  7494.      "\\SERVER\SHARE" };             /* name of server and share point */
  7495.  
  7496.  DosFSAttach("X:", "LAN", szShareName, sizeof(szShareName),
  7497.          FS_ATTACH, 0L);
  7498.      .
  7499.      .
  7500.      .
  7501.  DosFSAttach("X:", "LAN", szShareName, sizeof(szShareName),
  7502.          FS_DETACH, 0L);
  7503.  
  7504.  
  7505.  
  7506.  
  7507.  
  7508.  See Also
  7509.  
  7510.  DosFSCtl, DosQFSAttach
  7511.  
  7512.  
  7513.  █    DosFSCtl
  7514.  ────────────────────────────────────────────────────────────────────────────
  7515.  
  7516.  USHORT DosFSCtl  (pbData, cbData, pcbData, pbParms, cbParm, pcbParm,
  7517.  usFunct, pszRoute, hf, usRouteMethod, ulReserved)
  7518.  
  7519.  PBYTE  pbData;                    /*pointer to data buffer */
  7520.  
  7521.  USHORT  cbData;                   /*buffer length */
  7522.  
  7523.  PUSHORT  pcbData;                 /*pointer to buffer for actual length */
  7524.  
  7525.  PBYTE  pbParms;                   /*pointer to parameter list */
  7526.  
  7527.  USHORT  cbParm;                   /*size of parameter list */
  7528.  
  7529.  PUSHORT  pcbParm;                 /*pointer to buffer for actual length */
  7530.  
  7531.  USHORT  usFunct;                  /*function code */
  7532.  
  7533.  PSZ  pszRoute;                    /*pointer to file-system name */
  7534.  
  7535.  HFILE  hf;                        /*file or device handle */
  7536.  
  7537.  USHORT  usRouteMethod;            /*routing method */
  7538.  
  7539.  ULONG  ulReserved;                /*must be zero */
  7540.  
  7541.  
  7542.  The DosFSCtl function is used to call functions provided in a file system
  7543.  that are not part of the standard set of I/O functions.
  7544.  
  7545.  
  7546.  Parameters
  7547.  
  7548.  pbData  Points to the buffer that receives data from the nonstandard
  7549.  function.
  7550.  
  7551.  cbData  Specifies the length (in bytes) of the buffer pointed to by the
  7552.  pbData parameter. If this value is not at least as large as the value
  7553.  pointed to by the pcbData parameter, the system returns the
  7554.  ERROR_BUFFER_OVERFLOW error value and the value pointed to by pcbData will
  7555.  contain the correct length.
  7556.  
  7557.  pcbData  Points to the variable that receives the actual length of data
  7558.  returned.
  7559.  
  7560.  pbParms  Points to a list of command-specific parameters.
  7561.  
  7562.  cbParm  Specifies the length (in bytes) of the pbParms parameter. If the
  7563.  buffer size is insufficient, the error value ERROR_BUFFER_OVERFLOW will is
  7564.  returned and pcbParm will contain the size of buffer needed.
  7565.  
  7566.  pcbParm  Points to the variable that contains the length of the commands
  7567.  passed to the function and, on return, contains the length of the commands
  7568.  returned by the function.
  7569.  
  7570.  usFunct  Specifies a function code specific to the file system. This
  7571.  parameter can be one of the following values:
  7572.  
  7573.  Value                             Meaning
  7574.  ────────────────────────────────────────────────────────────────────────────
  7575.  
  7576.  0x0000─0x7FFF                     Reserved for MS OS/2.
  7577.  
  7578.  0x8000─0xBFFF                     Functions to be handled by local file
  7579.                                    systems.
  7580.  
  7581.  0xC000─0xFFFF                     Functions to be handled by remote file
  7582.                                    systems.
  7583.  
  7584.  
  7585.  
  7586.  pszRoute  Points to the string that contains the name of the file system or
  7587.  the path of a file or directory that the operation applies to.
  7588.  
  7589.  hf  Identifies the file or device.
  7590.  
  7591.  usRouteMethod  Specifies how the request will be routed. This parameter can
  7592.  be one of the following values:
  7593.  
  7594.  Value                             Meaning
  7595.  ────────────────────────────────────────────────────────────────────────────
  7596.  
  7597.  FSCTL_HANDLE                      Route via the file handle. The pszRoute
  7598.                                    parameter must be NULL, and the hf
  7599.                                    parameter must be a valid file or device
  7600.                                    handle.
  7601.  
  7602.  FSCTL_PATHNAME                    Route via a path. The hf parameter must
  7603.                                    be -1, and the pszRoute parameter must
  7604.                                    be a valid MS OS/2 path.
  7605.  
  7606.  FSCTL_FSDNAME                     Route via a file-system name. The hf
  7607.                                    parameter must be -1 and the pszRoute
  7608.                                    parameter must point to the name of a
  7609.                                    valid file system.
  7610.  
  7611.  
  7612.  
  7613.  ulReserved  Specifies a reserved value; must be zero.
  7614.  
  7615.  
  7616.  Return Value
  7617.  
  7618.  The return value is zero if the function is successful. Otherwise, it is an
  7619.  error value, which may be one of the following:
  7620.  
  7621.       ERROR_BUFFER_OVERFLOW
  7622.       ERROR_INTERRUPT
  7623.       ERROR_INVALID_CATEGORY
  7624.       ERROR_INVALID_FSD_NAME
  7625.       ERROR_INVALID_FUNCTION
  7626.       ERROR_INVALID_HANDLE
  7627.       ERROR_INVALID_LEVEL
  7628.       ERROR_INVALID_PARAMETER
  7629.       ERROR_NOT_SUPPORTED
  7630.  
  7631.  
  7632.  
  7633.  
  7634.  
  7635.  Comments
  7636.  
  7637.  A usFunct value of 0x0001 returns new error code information from the file
  7638.  system value of 0x0002 returns the maximum size of individual extended
  7639.  attributes in the first word of the buffer pointed to by pbData and the
  7640.  maximum size of the full extended-attribute list in the second word of the
  7641.  buffer.
  7642.  
  7643.  
  7644.  See Also
  7645.  
  7646.  DosFSAttach
  7647.  
  7648.  
  7649.  █    DosGetDBCSEv
  7650.  ────────────────────────────────────────────────────────────────────────────
  7651.  
  7652.  USHORT DosGetDBCSEv  (cbBuf, pctryc, pchBuf)
  7653.  
  7654.  USHORT  cbBuf;                    /*length of buffer */
  7655.  
  7656.  PCOUNTRYCODE  pctryc;             /*pointer to structure for country code
  7657.                                    */
  7658.  
  7659.  PCHAR  pchBuf;                    /*pointer to buffer for DBCS information
  7660.                                    */
  7661.  
  7662.  
  7663.  The DosGetDBCSEv function retrieves the double-byte character set (DBCS)
  7664.  environment vector for the given country code and code-page identifier.
  7665.  
  7666.  The DosGetDBCSEv function is a family API function.
  7667.  
  7668.  
  7669.  Parameters
  7670.  
  7671.  cbBuf  Specifies the size (in bytes) of the buffer that receives the DBCS
  7672.  environment vector.
  7673.  
  7674.  pctryc  Points to the COUNTRYCODE structure that contains the country code
  7675.  and code-page identifier used to retrieve the DBCS environment vector. The
  7676.  COUNTRYCODE structure has the following form:
  7677.  
  7678.  typedef struct _COUNTRYCODE {
  7679.      USHORT country;
  7680.      USHORT codepage;
  7681.  } COUNTRYCODE;
  7682.  
  7683.  
  7684.  
  7685.  
  7686.  For a full description, see Chapter 4, "Types, Macros, Structures."
  7687.  
  7688.  pchBuf  Points to the buffer that receives the country-dependent DBCS
  7689.  environment vector.
  7690.  
  7691.  
  7692.  Return Value
  7693.  
  7694.  The return value is zero if the function is successful. Otherwise, it is an
  7695.  error value, which may be one of the following:
  7696.  
  7697.       ERROR_NLS_BAD_TYPE
  7698.       ERROR_NLS_NO_COUNTRY_FILE
  7699.       ERROR_NLS_NO_CTRY_CODE
  7700.       ERROR_NLS_OPEN_FAILED
  7701.       ERROR_NLS_TABLE_TRUNCATED
  7702.       ERROR_NLS_TYPE_NOT_FOUND
  7703.  
  7704.  
  7705.  Comments
  7706.  
  7707.  The DBCS environment vector defines the low and high ranges for the DBCS
  7708.  lead-byte values.
  7709.  
  7710.  The DosGetDBCSEv function copies the information from the country.sys file
  7711.  to a buffer. The first two bytes in the environment vector specify the low
  7712.  and high values in the range for the DBCS lead-byte values. The last two
  7713.  bytes are both set to zero. The form of the information is similar to the
  7714.  following:
  7715.  
  7716.  BYTE low1, high1;
  7717.  BYTE low, high2;
  7718.      .
  7719.      .
  7720.      .
  7721.  BYTE lown, highn;
  7722.  BYTE 0, 0;
  7723.  
  7724.  
  7725.  
  7726.  
  7727.  If the buffer is too small to hold all of the information, the DosGetDBCSEv
  7728.  function truncates the information. To avoid this, make sure the buffer is
  7729.  at least ten bytes long. You can verify that all information has been copied
  7730.  by checking the last two bytes to make sure they are zeros. If the structure
  7731.  is larger than the information, the function fills any remaining bytes with
  7732.  zeros.
  7733.  
  7734.  
  7735.  Restrictions
  7736.  
  7737.  In real mode, the following restriction applies to the DosGetDBCSEv
  7738.  function:
  7739.  
  7740.    ■   There is no method of identifying the boot drive. The system assumes
  7741.        that the country.sys file is in the root directory of the current
  7742.        drive.
  7743.  
  7744.  
  7745.  
  7746.  
  7747.  See Also
  7748.  
  7749.  DosCaseMap, DosGetCollate, DosGetCp, DosGetCtryInfo, DosSetCp, VioGetCp,
  7750.  VioSetCp
  7751.  
  7752.  
  7753.  Corrections
  7754.  
  7755.  The DosGetDBCSEv function returns only the range for the leading byte of the
  7756.  character set, not the range of the trailing byte.
  7757.  
  7758.  
  7759.  █    DosGetModHandle
  7760.  ────────────────────────────────────────────────────────────────────────────
  7761.  
  7762.  USHORT DosGetModHandle  (pszModName, phMod)
  7763.  
  7764.  PSZ  pszModName;                  /*pointer to module name */
  7765.  
  7766.  PHMODULE  phMod;                  /*pointer to variable receiving module
  7767.                                    handle */
  7768.  
  7769.  
  7770.  The DosGetModHandle function retrieves the handle of a dynamic-link module.
  7771.  The DosGetModHandle function is typically used to make sure that a module
  7772.  has been loaded into memory. If the module has not been loaded, the function
  7773.  returns ERROR_MOD_NOT_FOUND, and the DosLoadModule function must be used to
  7774.  load the module.
  7775.  
  7776.  
  7777.  Parameters
  7778.  
  7779.  pszModName  Points to the null-terminated string that specifies the module
  7780.  name. This string must be a valid MS OS/2 filename. If it does not specify a
  7781.  path and the filename extension, the function appends the default extension
  7782.  (.dll) and searches for the dynamic-link module in the directories specified
  7783.  by the libpath command in the config.sys file.
  7784.  
  7785.  phMod  Points to the variable that receives the module handle.
  7786.  
  7787.  
  7788.  Return Value
  7789.  
  7790.  The return value is zero if the function is successful. Otherwise, it is an
  7791.  error value, which may be one of the following:
  7792.  
  7793.       ERROR_INTERRUPT
  7794.       ERROR_MOD_NOT_FOUND
  7795.  
  7796.  
  7797.  
  7798.  
  7799.  
  7800.  Example
  7801.  
  7802.  This example calls DosGetModHandle to determine whether the dynamic-link
  7803.  module mydll.dll is currently in memory. If mydll.dll is not in memory,
  7804.  DosGetModHandle calls DosLoadModule to load it. It then calls DosGetModName
  7805.  to get the full path of the module. (This example is accurate if mydll.dll
  7806.  exists in a directory defined by the libpath command in the config.sys
  7807.  file.)
  7808.  
  7809.  USHORT usError;
  7810.  HMODULE hmod;
  7811.  UCHAR szFailName[CCHMAXPATH], szModName[CCHMAXPATH];
  7812.  
  7813.  if (usError = DosGetModHandle("mydll", &hmod)) {
  7814.      if (usError == ERROR_MOD_NOT_FOUND)
  7815.          DosLoadModule(szFailName, sizeof(szFailName),
  7816.              "mydll", &hmod);
  7817.  }
  7818.  DosGetModName(hmod, sizeof(szModName), szModName);
  7819.  
  7820.  
  7821.  
  7822.  
  7823.  
  7824.  See Also
  7825.  
  7826.  DosFreeModule, DosGetModName, DosLoadModule
  7827.  
  7828.  
  7829.  Corrections
  7830.  
  7831.  If the pszModName parameter does not specify a path and the filename
  7832.  extension, the DosGetModHandle function appends the default extension (.dll)
  7833.  and searches for the dynamic-link module in the directories specified by the
  7834.  libpath command in the config.sys file.
  7835.  
  7836.  
  7837.  █    DosGetResource
  7838.  ────────────────────────────────────────────────────────────────────────────
  7839.  
  7840.  USHORT DosGetResource  (hmod, idType, idName, psel)
  7841.  
  7842.  HMODULE  hmod;                    /*module handle */
  7843.  
  7844.  USHORT  idType;                   /*resource-type identifier */
  7845.  
  7846.  USHORT  idName;                   /*resource-name identifier */
  7847.  
  7848.  PSEL  psel;                       /*pointer to variable for resource
  7849.                                    selector */
  7850.  
  7851.  
  7852.  The DosGetResource function retrieves the specified resource from a
  7853.  specified executable file. The function allocates a segment, copies the
  7854.  resource into the segment, and returns the segment selector. A process can
  7855.  use this segment selector to access the resource directly.
  7856.  
  7857.  This function is included in MS OS/2 versions 1.2 and later for
  7858.  compatibility purposes only. All new applications should use the
  7859.  DosGetResource2 function, which returns a far pointer to the resource,
  7860.  rather than a selector.
  7861.  
  7862.  
  7863.  Parameters
  7864.  
  7865.  hmod  Identifies the module that contains the resource. This parameter can
  7866.  be either the module handle returned by the DosLoadModule function or NULL
  7867.  for the application's module.
  7868.  
  7869.  idType  Specifies the type of resource to retrieve.
  7870.  
  7871.  idName  Specifies the name of the resource to retrieve.
  7872.  
  7873.  psel  Points to the variable that receives the selector of the segment
  7874.  containing the resource.
  7875.  
  7876.  
  7877.  Return Value
  7878.  
  7879.  The return value is zero if the function is successful. Otherwise, it is an
  7880.  error value, which may be one of the following:
  7881.  
  7882.       ERROR_CANT_FIND_RESOURCE
  7883.       ERROR_INVALID_HANDLE
  7884.       ERROR_INVALID_MODULE
  7885.       ERROR_INVALID_SELECTOR
  7886.  
  7887.  
  7888.  
  7889.  
  7890.  
  7891.  Comments
  7892.  
  7893.  The following list describes the predefined types that can be used for the
  7894.  idType parameter:
  7895.  
  7896.  Type                              Meaning
  7897.  ────────────────────────────────────────────────────────────────────────────
  7898.  
  7899.  RT_ACCELTABLE                     Accelerator tables
  7900.  
  7901.  RT_BITMAP                         Bitmap
  7902.  
  7903.  RT_CHARTBL                        Glyph-to-character tables
  7904.  
  7905.  RT_DIALOG                         Dialog template
  7906.  
  7907.  RT_DISPLAYINFO                    Screen-display information
  7908.  
  7909.  RT_DLGINCLUDE                     Dialog include file
  7910.  
  7911.  RT_FONT                           Font
  7912.  
  7913.  RT_FONTDIR                        Font directory
  7914.  
  7915.  RT_HELPSUBTABLE                   Help-subtable resource
  7916.  
  7917.  RT_HELPTABLE                      Help-table resource
  7918.  
  7919.  RT_KEYTBL                         Key to UGL tables
  7920.  
  7921.  RT_MENU                           Menu template
  7922.  
  7923.  RT_MESSAGE                        Error-message tables
  7924.  
  7925.  RT_POINTER                        Mouse-pointer shape
  7926.  
  7927.  RT_RCDATA                         Binary data
  7928.  
  7929.  RT_STRING                         String tables
  7930.  
  7931.  RT_VKEYTBL                        Key to virtual-key tables
  7932.  
  7933.  
  7934.  
  7935.  See Also
  7936.  
  7937.  DosGetResource2, DosLoadModule
  7938.  
  7939.  
  7940.  Changes
  7941.  
  7942.  This function is included in MS OS/2 versions 1.2 and later for
  7943.  compatibility purposes only. All new applications should use
  7944.  DosGetResource2.
  7945.  
  7946.  
  7947.  █    DosGetResource2
  7948.  ────────────────────────────────────────────────────────────────────────────
  7949.  
  7950.  USHORT DosGetResource2  (hmod, idType, idName, ppData)
  7951.  
  7952.  HMODULE  hmod;                    /*module handle */
  7953.  
  7954.  USHORT  idType;                   /*resource-type identifier */
  7955.  
  7956.  USHORT  idName;                   /*resource-name identifier */
  7957.  
  7958.  PVOID FAR *  ppData;              /*pointer to variable for resource
  7959.                                    address */
  7960.  
  7961.  
  7962.  The DosGetResource2 function retrieves a pointer to a resource.
  7963.  
  7964.  
  7965.  Parameters
  7966.  
  7967.  hmod  Identifies the module that contains the resource. This parameter can
  7968.  be the module handle returned by the DosLoadModule function or NULL for the
  7969.  application's module.
  7970.  
  7971.  idType  Specifies the type of resource to retrieve.
  7972.  
  7973.  idName  Specifies the name of the resource to retrieve.
  7974.  
  7975.  ppData  Points to the variable that receives the pointer to the resource.
  7976.  
  7977.  
  7978.  Return Value
  7979.  
  7980.  The return value is zero if the function is successful. Otherwise, it is an
  7981.  error value, which may be one of the following:
  7982.  
  7983.       ERROR_INVALID_PARAMETER
  7984.       ERROR_INVALID_MODULETYPE
  7985.  
  7986.  
  7987.  
  7988.  
  7989.  
  7990.  Comments
  7991.  
  7992.  The DosGetResource2 function allocates a segment, copies the resource into
  7993.  the segment, and returns a pointer to the resource. A process can use this
  7994.  pointer to access the resource directly. For compatibility with future
  7995.  versions of MS OS/2, this function should be used instead of the
  7996.  DosGetResource function, which returns a selector instead of a pointer.
  7997.  
  7998.  The following list describes the predefined types that can be used for the
  7999.  idType parameter:
  8000.  
  8001.  Type                              Meaning
  8002.  ────────────────────────────────────────────────────────────────────────────
  8003.  
  8004.  RT_ACCELTABLE                     Accelerator tables
  8005.  
  8006.  RT_BITMAP                         Bitmap
  8007.  
  8008.  RT_CHARTBL                        Glyph-to-character tables
  8009.  
  8010.  RT_DIALOG                         Dialog template
  8011.  
  8012.  RT_DISPLAYINFO                    Screen-display information
  8013.  
  8014.  RT_DLGINCLUDE                     Dialog include file
  8015.  
  8016.  RT_FONT                           Font
  8017.  
  8018.  RT_FONTDIR                        Font directory
  8019.  
  8020.  RT_HELPSUBTABLE                   Help-subtable resource
  8021.  
  8022.  RT_HELPTABLE                      Help-table resource
  8023.  
  8024.  RT_KEYTBL                         Key to UGL tables
  8025.  
  8026.  RT_MENU                           Menu template
  8027.  
  8028.  RT_MESSAGE                        Error-message tables
  8029.  
  8030.  RT_POINTER                        Mouse-pointer shape
  8031.  
  8032.  RT_RCDATA                         Binary data
  8033.  
  8034.  RT_STRING                         String tables
  8035.  
  8036.  RT_VKEYTBL                        Key to virtual-key tables
  8037.  
  8038.  
  8039.  
  8040.  Example
  8041.  
  8042.  This example calls DosGetResource2 to retrieve a resource from the
  8043.  application's module, and then calls DosFreeResource to free the memory used
  8044.  by the resource:
  8045.  
  8046.  PBYTE pResource;
  8047.  
  8048.  if (!DosGetResource2(
  8049.          (HMODULE) NULL,      /* loads from application's module */
  8050.          RT_MENU,             /* gets menu resource              */
  8051.          IDM_MENU,            /* ID of menu to get               */
  8052.          &pResource)) {       /* pointer address                 */
  8053.      .
  8054.      .
  8055.      .
  8056.      DosFreeResource(pResource);  /* frees resource              */
  8057.  
  8058.  
  8059.  
  8060.  
  8061.  
  8062.  See Also
  8063.  
  8064.  DosFreeResource, DosGetResource, DosLoadModule
  8065.  
  8066.  
  8067.  █    DosGetVersion
  8068.  ────────────────────────────────────────────────────────────────────────────
  8069.  
  8070.  USHORT DosGetVersion  (pusVersion)
  8071.  
  8072.  PUSHORT  pusVersion;              /*pointer to variable receiving version
  8073.                                    number */
  8074.  
  8075.  
  8076.  The DosGetVersion function retrieves the version number of the operating
  8077.  system. For MS OS/2 version 1.1, both the major and minor version numbers
  8078.  are 10. For MS OS/2 version 1.2, the minor version number is 20.
  8079.  
  8080.  The DosGetVersion function is a family API function.
  8081.  
  8082.  
  8083.  Parameters
  8084.  
  8085.  pusVersion  Points to the variable that receives the version number. The
  8086.  high-order byte is set to the major version number; the low-order byte is
  8087.  set to the minor version number.
  8088.  
  8089.  
  8090.  Return Value
  8091.  
  8092.  The return value is zero if the function is successful. Otherwise, it is an
  8093.  error value.
  8094.  
  8095.  
  8096.  Example
  8097.  
  8098.  This example retrieves and displays the major and minor version number:
  8099.  
  8100.  USHORT usVersion;
  8101.  CHAR ch;
  8102.  
  8103.  DosGetVersion(&usVersion);
  8104.  ch = (HIBYTE(usVersion) / 10) + '0'; /* gets maj. version number */
  8105.  VioWrtTTY("You are using MS OS/2 version ", 30, 0);
  8106.  VioWrtTTY(&ch, 1, 0);
  8107.  VioWrtTTY(".", 1, 0);
  8108.  ch = (LOBYTE(usVersion) / 10) + '0'; /* gets min. version number */
  8109.  VioWrtTTY(&ch, 1, 0);
  8110.  VioWrtTTY("\r\n", 2, 0);
  8111.  
  8112.  
  8113.  
  8114.  
  8115.  
  8116.  See Also
  8117.  
  8118.  DosQSysInfo
  8119.  
  8120.  
  8121.  Corrections
  8122.  
  8123.  The example incorrectly retrieved the minor version number, instead of the
  8124.  major version number. It has been changed to show how to get and display
  8125.  both major and minor version numbers.
  8126.  
  8127.  
  8128.  █    DosLoadModule
  8129.  ────────────────────────────────────────────────────────────────────────────
  8130.  
  8131.  USHORT DosLoadModule  (pszFailName, cbFileName, pszModName, phmod)
  8132.  
  8133.  PSZ  pszFailName;                 /*pointer to buffer for name if failure
  8134.                                    */
  8135.  
  8136.  USHORT  cbFileName;               /*length of buffer for name if failure
  8137.                                    */
  8138.  
  8139.  PSZ  pszModName;                  /*pointer to module name */
  8140.  
  8141.  PHMODULE  phmod;                  /*pointer to variable for module handle
  8142.                                    */
  8143.  
  8144.  
  8145.  The DosLoadModule function loads a dynamic-link module and returns a handle
  8146.  for the module. You can use the module handle to retrieve the entry
  8147.  addresses of procedures in the module and to retrieve information about the
  8148.  module.
  8149.  
  8150.  
  8151.  Parameters
  8152.  
  8153.  pszFailName  Points to the buffer that receives a null-terminated string.
  8154.  The DosLoadModule function copies a string to the buffer only if the
  8155.  function fails to load the module. The string identifies the dynamic-link
  8156.  module responsible for the failure. This module may be other than the one
  8157.  specified in the pszModName parameter if the specified module links to other
  8158.  dynamic-link modules.
  8159.  
  8160.  cbFileName  Specifies the length (in bytes) of the buffer pointed to by the
  8161.  pszFailName parameter.
  8162.  
  8163.  pszModName  Points to the null-terminated string that specifies the module
  8164.  name. This string must be a valid MS OS/2 filename. If it does not specify a
  8165.  path and the filename extension, the function appends the default extension
  8166.  (.dll) and searches for the dynamic-link module in the directories specified
  8167.  by the libpath command in the config.sys file.
  8168.  
  8169.  phmod  Points to the variable that receives the handle of the dynamic-link
  8170.  module.
  8171.  
  8172.  
  8173.  Return Value
  8174.  
  8175.  The return value is zero if the function is successful. Otherwise, it is an
  8176.  error value, which may be one of the following:
  8177.  
  8178.       ERROR_BAD_FORMAT
  8179.       ERROR_FILE_NOT_FOUND
  8180.       ERROR_INTERRUPT
  8181.       ERROR_INVALID_MINALLOCSIZE
  8182.       ERROR_INVALID_NAME
  8183.       ERROR_NOT_ENOUGH_MEMORY
  8184.  
  8185.  
  8186.  
  8187.  
  8188.  
  8189.  Comments
  8190.  
  8191.  The DosLoadModule function loads only MS OS/2 dynamic-link modules. Attempts
  8192.  to load other executable files (such as MS-DOS executable files) result in
  8193.  an error.
  8194.  
  8195.  
  8196.  Example
  8197.  
  8198.  This example calls the DosLoadModule function to load the dynamic-link
  8199.  module qhdll.dll. This example then calls the DosGetProcAddr function to
  8200.  retrieve the address of the BOXMESSAGE function that is defined in the
  8201.  module. After calling the BOXMESSAGE function, the example calls
  8202.  DosFreeModule to free the dynamic-link module. (This example is accurate if
  8203.  qhdll.dll exists in a directory defined by the libpath command of the
  8204.  config.sys file, and if qhdll.dll contains the BOXMESSAGE function that uses
  8205.  the Pascal calling convention.)
  8206.  
  8207.  UCHAR szFailName[CCHMAXPATH];
  8208.  HMODULE hmod;
  8209.  VOID (PASCAL FAR *pfnBoxMsg)(PSZ, BYTE, BYTE, SHANDLE, SHANDLE, BOOL);
  8210.  
  8211.  DosLoadModule(szFailName,        /* failure name buffer         */
  8212.      sizeof(szFailName),          /* size of failure name buffer */
  8213.      "qhdll",                     /* module name                 */
  8214.      &hmod);                      /* address of handle           */
  8215.  DosGetProcAddr(hmod, "BOXMESSAGE", &pfnBoxMsg);
  8216.  pfnBoxMsg("Hello World", 0x30, 1, 0, 0, FALSE);
  8217.  DosFreeModule(hmod);
  8218.  
  8219.  
  8220.  
  8221.  
  8222.  
  8223.  See Also
  8224.  
  8225.  DosExecPgm, DosFreeModule, DosGetModName, DosGetProcAddr
  8226.  
  8227.  
  8228.  Corrections
  8229.  
  8230.  If the pszModName parameter does not specify a path and the filename
  8231.  extension, DosLoadModule function appends the default extension (.dll) and
  8232.  searches for the dynamic-link module in the directories specified by the
  8233.  libpath command in the config.sys file.
  8234.  
  8235.  
  8236.  █    DosMakePipe
  8237.  ────────────────────────────────────────────────────────────────────────────
  8238.  
  8239.  USHORT DosMakePipe  (phfRead, phfWrite, cbPipe)
  8240.  
  8241.  PHFILE  phfRead;                  /*pointer to variable for read handle */
  8242.  
  8243.  PHFILE  phfWrite;                 /*pointer to variable for write handle
  8244.                                    */
  8245.  
  8246.  USHORT  cbPipe;                   /*number of bytes reserved for pipe */
  8247.  
  8248.  
  8249.  The DosMakePipe function creates a pipe. The function creates the pipe,
  8250.  assigning the specified pipe size to the storage buffer, and also creates
  8251.  handles that the process can use to read from and write to the buffer in
  8252.  subsequent calls to the DosRead and DosWrite functions.
  8253.  
  8254.  
  8255.  Parameters
  8256.  
  8257.  phfRead  Points to the variable that receives the read handle for the pipe.
  8258.  
  8259.  phfWrite  Points to the variable that receives the write handle for the
  8260.  pipe.
  8261.  
  8262.  cbPipe  Specifies the size (in bytes) to allocate for the storage buffer for
  8263.  this pipe. This can be any value up to 65,536 minus the size of the pipe
  8264.  header, which is currently 32 bytes. If this parameter is zero, the default
  8265.  buffer size is used. (The buffer size is advisory only. MS OS/2 may allocate
  8266.  more or less space.)
  8267.  
  8268.  
  8269.  Return Value
  8270.  
  8271.  The return value is zero if the function is successful. Otherwise, it is an
  8272.  error value, which may be one of the following:
  8273.  
  8274.       ERROR_NOT_ENOUGH_MEMORY
  8275.       ERROR_TOO_MANY_OPEN_FILES
  8276.  
  8277.  
  8278.  
  8279.  
  8280.  
  8281.  Comments
  8282.  
  8283.  Pipes are typically used by a pair of processes. One process creates the
  8284.  pipe and passes a handle to the other process. This lets one process write
  8285.  into the pipe and the other read from the pipe. Since MS OS/2 provides no
  8286.  permission checks on pipes, the cooperating processes must ensure that they
  8287.  do not attempt to write to or read from the pipe at the same time.
  8288.  
  8289.  When all of a pipe's handles are closed by using the DosClose function, MS
  8290.  OS/2 deletes that pipe. If two processes are communicating by using a pipe
  8291.  and the process that is reading the pipe ends, the next call to the DosWrite
  8292.  function for that pipe returns the "broken pipe" error value.
  8293.  
  8294.  MS OS/2 temporarily blocks any call to the DosWrite function that would
  8295.  write more data to the pipe than can fit in the storage buffer. The system
  8296.  removes the block as soon as enough data is read from the pipe to make room
  8297.  for the remaining unwritten data.
  8298.  
  8299.  
  8300.  See Also
  8301.  
  8302.  DosClose, DosDupHandle, DosRead, DosWrite
  8303.  
  8304.  
  8305.  Changes
  8306.  
  8307.  The cbPipe parameter is advisory only. The actual buffer space allocated by
  8308.  the system may be larger (to a maximum of 65,536 minus the pipe header size)
  8309.  or smaller.
  8310.  
  8311.  
  8312.  █    DosMkDir2
  8313.  ────────────────────────────────────────────────────────────────────────────
  8314.  
  8315.  USHORT DosMkDir2  (pszDir, peaop, ulReserved)
  8316.  
  8317.  PSZ  pszDir;                      /*pointer to directory name */
  8318.  
  8319.  PEAOP  peaop;                     /*pointer to structure for extended
  8320.                                    attributes */
  8321.  
  8322.  ULONG  ulReserved;                /*must be zero */
  8323.  
  8324.  
  8325.  The DosMkDir2 function creates a directory.
  8326.  
  8327.  
  8328.  Parameters
  8329.  
  8330.  pszDir  Points to a null-terminated string that specifies a valid MS OS/2
  8331.  directory name.
  8332.  
  8333.  peaop  Points to the EAOP structure that defines extended attributes for the
  8334.  directory.
  8335.  
  8336.  The EAOP structure has the following form:
  8337.  
  8338.  typedef struct _EAOP {
  8339.      PGEALIST fpGEAList;
  8340.      PFEALIST fpFEAList;
  8341.      ULONG    oError;
  8342.  } EAOP;
  8343.  
  8344.  
  8345.  
  8346.  
  8347.  For a full description, see Chapter 4, "Types, Macros, Structures."
  8348.  
  8349.  ulReserved  Specifies a reserved value; must be zero.
  8350.  
  8351.  
  8352.  Return Value
  8353.  
  8354.  The return value is zero if the function is successful. Otherwise, it is an
  8355.  error value, which may be one of the following:
  8356.  
  8357.       ERROR_ACCESS_DENIED
  8358.       ERROR_EA_LIST_INCONSISTENT
  8359.       ERROR_FILENAME_EXCED_RANGE
  8360.       ERROR_INVALID_EA_NAME
  8361.       ERROR_PATH_NOT_FOUND
  8362.  
  8363.  
  8364.  
  8365.  
  8366.  
  8367.  Comments
  8368.  
  8369.  Prior to the function call, the fpFEAList field of the EAOP structure should
  8370.  be set to point to the buffer that contains the relevant list of extended
  8371.  attributes.
  8372.  
  8373.  If the peaop parameter is NULL, no extended attributes are defined for the
  8374.  directory.
  8375.  
  8376.  If an error occurs during the creation of the extended attributes, the
  8377.  oError field of the EAOP structure will contain the offset within the list
  8378.  where the error occurred.
  8379.  
  8380.  
  8381.  See Also
  8382.  
  8383.  DosMkDir
  8384.  
  8385.  
  8386.  █    DosMonReg
  8387.  ────────────────────────────────────────────────────────────────────────────
  8388.  
  8389.  USHORT DosMonReg  (hmon, pbInBuf, pbOutBuf, fPosition, usIndex)
  8390.  
  8391.  HMONITOR  hmon;                   /*monitor handle to register */
  8392.  
  8393.  PBYTE  pbInBuf;                   /*pointer to structure for input buffer
  8394.                                    */
  8395.  
  8396.  PBYTE  pbOutBuf;                  /*pointer to structure for output buffer
  8397.                                    */
  8398.  
  8399.  USHORT  fPosition;                /*position flag */
  8400.  
  8401.  USHORT  usIndex;                  /*index */
  8402.  
  8403.  
  8404.  The DosMonReg function registers a monitor by placing it in a chain of other
  8405.  monitors for the same device. Each monitor receives input from or sends
  8406.  output to the device in the order in which it appears in the chain.
  8407.  
  8408.  
  8409.  Parameters
  8410.  
  8411.  hmon  Identifies the monitor to register. This handle must have been created
  8412.  previously by using the DosMonOpen function.
  8413.  
  8414.  pbInBuf  Points to the MONIN structure that receives data from the device
  8415.  driver or from the previous monitor in the chain. The MONIN structure has
  8416.  the following form:
  8417.  
  8418.  typedef struct _MONIN {
  8419.      USHORT cb;
  8420.      BYTE abReserved[18];
  8421.      BYTE bBuffer[108];
  8422.  } MONIN;
  8423.  
  8424.  
  8425.  For a full description, see Chapter 4, "Types, Macros, Structures."
  8426.  
  8427.  pbOutBuf  Points to the MONOUT structure that receives data for the next
  8428.  monitor in the chain. The MONOUT structure has the following form:
  8429.  
  8430.  typedef struct _MONOUT {
  8431.      USHORT cb;
  8432.      BYTE abReserved[18];
  8433.      BYTE abBuffer[108];
  8434.  } MONOUT;
  8435.  
  8436.  
  8437.  
  8438.  
  8439.  For a full description, see Chapter 4, "Types, Macros, Structures."
  8440.  
  8441.  fPosition  Specifies the position of the monitor in the chain of input and
  8442.  output. This parameter can be one of the following values:
  8443.  
  8444.  Value                             Meaning
  8445.  ────────────────────────────────────────────────────────────────────────────
  8446.  
  8447.  MONITOR_BEGIN                     Place the monitor at the beginning of
  8448.                                    the chain, ahead of any other monitors
  8449.                                    in the chain.
  8450.  
  8451.  MONITOR_DEFAULT                   Place the monitor anywhere in the chain.
  8452.  
  8453.  MONITOR_END                       Place the monitor at the end of the
  8454.                                    chain.
  8455.  
  8456.  
  8457.  
  8458.  Any of the fPosition values can be combined with MONITOR_SPECIAL by using
  8459.  the OR operator to allow the monitor to continue to receive data even if the
  8460.  device is disabled or another monitor further down the chain is blocked. If
  8461.  the MONITOR_SPECIAL constant is not set, no monitors will receive input when
  8462.  the device driver is disabled or any monitor is blocked.
  8463.  
  8464.  usIndex  Specifies a device-specific value. If the device is the keyboard,
  8465.  usIndex specifies the ID for the screen group to monitor. If no screen-group
  8466.  number is available (the monitor is detached), the ID of the current
  8467.  foreground screen group can be obtained by calling DosGetInfoSeg. (The
  8468.  current foreground screen group is the group that most recently called
  8469.  KbdCharIn.)
  8470.  
  8471.  
  8472.  Return Value
  8473.  
  8474.  The return value is zero if the function is successful. Otherwise, it is an
  8475.  error value, which may be one of the following:
  8476.  
  8477.       ERROR_MON_BUFFER_TOO_SMALL
  8478.       ERROR_MON_INVALID_HANDLE
  8479.       ERROR_MON_INVALID_PARMS
  8480.       ERROR_NOT_ENOUGH_MEMORY
  8481.  
  8482.  
  8483.  
  8484.  
  8485.  
  8486.  Comments
  8487.  
  8488.  The MONIN and MONOUT structures must be in the same segment.
  8489.  
  8490.  
  8491.  See Also
  8492.  
  8493.  DosGetInfoSeg, DosMonClose, DosMonOpen, DosMonRead, DosMonWrite, KbdCharIn
  8494.  
  8495.  
  8496.  Changes
  8497.  
  8498.  A new value, MONITOR_SPECIAL, can be combined with any other position value
  8499.  for the fPosition parameter. This constant lets a monitor receive input even
  8500.  if the device is disabled or another monitor in the chain is blocked.
  8501.  
  8502.  
  8503.  █    DosOpen
  8504.  ────────────────────────────────────────────────────────────────────────────
  8505.  
  8506.  USHORT DosOpen  (pszFileName, phf, pusAction, ulFileSize, usAttribute,
  8507.  fsOpenFlags, fsOpenMode, ulReserved)
  8508.  
  8509.  PSZ  pszFileName;                 /*pointer to filename */
  8510.  
  8511.  PHFILE  phf;                      /*pointer to variable for file handle */
  8512.  
  8513.  PUSHORT  pusAction;               /*pointer to variable for action taken
  8514.                                    */
  8515.  
  8516.  ULONG  ulFileSize;                /*file size if file is created or
  8517.                                    truncated */
  8518.  
  8519.  USHORT  usAttribute;              /*file attribute */
  8520.  
  8521.  USHORT  fsOpenFlags;              /*action taken if file exists/does not
  8522.                                    exist */
  8523.  
  8524.  USHORT  fsOpenMode;               /*open mode of file */
  8525.  
  8526.  ULONG  ulReserved;                /*must be zero */
  8527.  
  8528.  
  8529.  The DosOpen function opens an existing file or creates a new file. This
  8530.  function returns a handle that can be used to read from and write to the
  8531.  file, as well as to retrieve information about the file. The DosOpen
  8532.  function can also be used to open a device or a named pipe.
  8533.  
  8534.  The DosOpen function is a family API function.
  8535.  
  8536.  This function is included in MS OS/2 versions 1.2 and later for
  8537.  compatibility purposes only. All new applications should use the DosOpen2
  8538.  function.
  8539.  
  8540.  
  8541.  Parameters
  8542.  
  8543.  pszFileName  Points to the null-terminated string that specifies the name of
  8544.  the file to be opened. The string must be a valid MS OS/2 filename and must
  8545.  not contain wildcard characters.
  8546.  
  8547.  phf  Points to the variable that receives the handle of the opened file.
  8548.  
  8549.  pusAction  Points to the variable receiving the value that specifies the
  8550.  action taken by the DosOpen function. If DosOpen fails, this value has no
  8551.  meaning. Otherwise, it is one of the following values:
  8552.  
  8553.  Value                             Meaning
  8554.  ────────────────────────────────────────────────────────────────────────────
  8555.  
  8556.  FILE_CREATED                      File was created.
  8557.  
  8558.  FILE_EXISTED                      File already existed.
  8559.  
  8560.  FILE_TRUNCATED                    File existed and was truncated.
  8561.  
  8562.  
  8563.  
  8564.  ulFileSize  Specifies the file's new size (in bytes). This parameter applies
  8565.  only if the file is created or truncated. The size specification has no
  8566.  effect on a file that is opened only for reading.
  8567.  
  8568.  usAttribute  Specifies the file attributes. This parameter can be a
  8569.  combination of the following values:
  8570.  
  8571.  Value                             Meaning
  8572.  ────────────────────────────────────────────────────────────────────────────
  8573.  
  8574.  FILE_NORMAL                       File can be read from or written to.
  8575.  
  8576.  FILE_READONLY                     File can be read from, but not written
  8577.                                    to.
  8578.  
  8579.  FILE_HIDDEN                       File is hidden and does not appear in a
  8580.                                    directory listing.
  8581.  
  8582.  FILE_SYSTEM                       File is a system file.
  8583.  
  8584.  FILE_ARCHIVED                     File has been archived.
  8585.  
  8586.  
  8587.  
  8588.  File attributes apply only if the file is created.
  8589.  
  8590.  fsOpenFlags  Specifies the action to take both when the file exists and when
  8591.  it does not exist. This parameter can be one of the following values:
  8592.  
  8593.  Value                             Meaning
  8594.  ────────────────────────────────────────────────────────────────────────────
  8595.  
  8596.  FILE_CREATE                       Create a new file; fail if the file
  8597.                                    already exists.
  8598.  
  8599.  FILE_OPEN                         Open an existing file; fail if the file
  8600.                                    does not exist.
  8601.  
  8602.  FILE_OPEN | FILE_CREATE           Open an existing file, or create the
  8603.                                    file if it does not exist.
  8604.  
  8605.  FILE_TRUNCATE                     Open an existing file and change to a
  8606.                                    given size.
  8607.  
  8608.  FILE_TRUNCATE | FILE_CREATE       Open an existing file and truncate it,
  8609.                                    or create the file if it does not exist.
  8610.  
  8611.  
  8612.  
  8613.  fsOpenMode  Specifies the modes with which to open the file. This parameter
  8614.  consists of one access mode and one share mode. All other values are
  8615.  optional; one locality mode can be specified; and the other values can be
  8616.  given in any combination.
  8617.  
  8618.  Value                             Meaning
  8619.  ────────────────────────────────────────────────────────────────────────────
  8620.  
  8621.  OPEN_ACCESS_READONLY              Data can be read from the file but not
  8622.                                    written to it.
  8623.  
  8624.  OPEN_ACCESS_READWRITE             Data can be read from or written to the
  8625.                                    file.
  8626.  
  8627.  OPEN_ACCESS_WRITEONLY             Data can be written to the file but not
  8628.                                    read from it.
  8629.  
  8630.  OPEN_SHARE_DENYNONE               Other processes can open the file for
  8631.                                    any access: read-only, write-only, or
  8632.                                    read-write.
  8633.  
  8634.  OPEN_SHARE_DENYREAD               Other processes can open the file for
  8635.                                    write-only access, but they cannot open
  8636.                                    it for read-only or read-write access.
  8637.  
  8638.  OPEN_SHARE_DENYREADWRITE          The current process has exclusive access
  8639.                                    to the file. The file cannot be opened
  8640.                                    by any process (including the current
  8641.                                    process).
  8642.  
  8643.  OPEN_SHARE_DENYWRITE              Other processes can open the file for
  8644.                                    read-only access, but they cannot open
  8645.                                    it for write-only or read-write access.
  8646.  
  8647.  OPEN_FLAGS_DASD                   The file handle represents a physical
  8648.                                    drive that has been opened for direct
  8649.                                    access. (The pszFileName parameter must
  8650.                                    specify a drive name.) The DosDevIOCtl
  8651.                                    function can be used with this file
  8652.                                    handle to bypass the file system and to
  8653.                                    access the sectors of the drive directly.
  8654.  
  8655.  OPEN_FLAGS_FAIL_ON_ERROR          Any function that uses the file handle
  8656.                                    returns immediately with an error value
  8657.                                    if there is an I/O error─for example,
  8658.                                    when the drive door is open or a sector
  8659.                                    is missing. If this value is not
  8660.                                    specified, the system passes the error
  8661.                                    to the system critical-error handler,
  8662.                                    which then reports the error to the user
  8663.                                    with a hard-error pop-up message. The
  8664.                                    fail-on-error flag is not inherited by
  8665.                                    child processes. The fail-on-error flag
  8666.                                    applies to all functions that use the
  8667.                                    file handle, with the exception of the
  8668.                                    DosDevIOCtl function.
  8669.  
  8670.  OPEN_FLAGS_NOINHERIT              The file handle is not available to any
  8671.                                    child process started by the current
  8672.                                    process. If this value is not specified,
  8673.                                    any child process started by the current
  8674.                                    process can use the file handle.
  8675.  
  8676.  OPEN_FLAGS_WRITE_THROUGH          This flag applies to functions, such as
  8677.                                    DosWrite, that write data to the file.
  8678.                                    If this value is specified, the system
  8679.                                    writes data to the device before the
  8680.                                    given function returns. Otherwise, the
  8681.                                    system may store the data in an internal
  8682.                                    file buffer and write the data to the
  8683.                                    device only when the buffer is full or
  8684.                                    the file is closed.
  8685.  
  8686.  OPEN_FLAGS_NO_LOCALITY            There is no specific information
  8687.                                    regarding the locality of reference (the
  8688.                                    degree of randomness with which the file
  8689.                                    is accessed).
  8690.  
  8691.  OPEN_FLAGS_SEQUENTIAL             The file is accessed sequentially.
  8692.  
  8693.  OPEN_FLAGS_RANDOM                 The file is accessed randomly.
  8694.  
  8695.  OPEN_FLAGS_RANDOMSEQUENTIAL       The file is accessed randomly, but there
  8696.                                    is a degree of sequential I/O within
  8697.                                    that random access. For example, this
  8698.                                    flag is specified if large blocks of
  8699.                                    data are to be read or written at random
  8700.                                    locations in the file.
  8701.  
  8702.  OPEN_FLAGS_NO_CACHE               The disk drive should not cache data in
  8703.                                    I/O operations on this file.
  8704.  
  8705.  
  8706.  
  8707.  ulReserved  Specifies a reserved value; must be zero.
  8708.  
  8709.  
  8710.  Return Value
  8711.  
  8712.  The return value is zero if the function is successful. Otherwise, it is an
  8713.  error value, which may be one of the following:
  8714.  
  8715.       ERROR_ACCESS_DENIED
  8716.       ERROR_CANNOT_MAKE
  8717.       ERROR_DISK_FULL
  8718.       ERROR_DRIVE_LOCKED
  8719.       ERROR_FILE_NOT_FOUND
  8720.       ERROR_FILENAME_EXCED_RANGE
  8721.       ERROR_INVALID_ACCESS
  8722.       ERROR_INVALID_PARAMETER
  8723.       ERROR_NOT_DOS_DISK
  8724.       ERROR_OPEN_FAILED
  8725.       ERROR_PATH_NOT_FOUND
  8726.       ERROR_SHARING_BUFFER_EXCEEDED
  8727.       ERROR_SHARING_VIOLATION
  8728.       ERROR_TOO_MANY_OPEN_FILES
  8729.  
  8730.  
  8731.  
  8732.  
  8733.  
  8734.  Comments
  8735.  
  8736.  The ERROR_ACCESS_DENIED value is returned if you try to open a file in a
  8737.  mode that is incompatible with the file's current access and sharing
  8738.  modes─for example, if you attempt to open a read-only file for writing.
  8739.  
  8740.  The ERROR_SHARING_VIOLATION value is returned if some other process has
  8741.  opened the file with a sharing method that denies the type of access you
  8742.  have requested.
  8743.  
  8744.  Once the file is opened, the DosSetFHandState function can be used to change
  8745.  the OPEN_FLAGS_FAIL_ON_ERROR, OPEN_FLAGS_NOINHERIT, and
  8746.  OPEN_FLAGS_WRITE_THROUGH flags specified in fsOpenMode.
  8747.  
  8748.  MS OS/2 does not provide a built-in method to inform a child process that it
  8749.  has inherited a given file handle. The parent process must pass this
  8750.  information to a child process. If the file is created without the
  8751.  OPEN_FLAGS_NOINHERIT flag, and the parent process terminates without closing
  8752.  the file, the file will remain open until all child processes have
  8753.  terminated.
  8754.  
  8755.  The DosOpen function can be used to open the client end of a named pipe and
  8756.  return a handle of the pipe. The pipe must be in "listen" state for the open
  8757.  operation to succeed; otherwise the open operation fails and the
  8758.  ERROR_PIPE_BUSY error value is returned. Until a given instance of a named
  8759.  pipe has been closed by a client, that same instance cannot be opened by
  8760.  another client; however, the opening process can duplicate the open handle
  8761.  as many times as required. The access and sharing modes specified when a
  8762.  pipe is opened must be consistent with the modes specified in the call to
  8763.  the DosMakeNmPipe function. Pipes are always opened with the pipe-specific
  8764.  states set to lock, read, and write operations and are read as a byte
  8765.  stream.
  8766.  
  8767.  
  8768.  Restrictions
  8769.  
  8770.  In real mode, the following restrictions apply to the DosOpen function:
  8771.  
  8772.    ■   Only the access modes and the OPEN_FLAGS_DASD flag can be specified
  8773.        for the fsOpenMode parameter.
  8774.  
  8775.    ■   The Category 8 functions DSK_READTRACK and DSK_WRITETRACK are not
  8776.        supported in MS-DOS versions 3.x and 4.x. You cannot use the DosOpen
  8777.        function to read or write to a track when you are running MS-DOS.
  8778.  
  8779.  
  8780.  
  8781.  
  8782.  Example
  8783.  
  8784.  This example calls the DosOpen function to create a file abc that is 100
  8785.  bytes long and open it for write-only access. The fsOpenFlags parameter is
  8786.  set to FILE_CREATE so that DosOpen will return an error if the file already
  8787.  exists.
  8788.  
  8789.  HFILE hf;
  8790.  USHORT usAction;
  8791.  DosOpen("abc",                      /* filename to open       */
  8792.      &hf,                            /* address of file handle */
  8793.      &usAction,                      /* action taken           */
  8794.      100L,                           /* size of new file       */
  8795.      FILE_NORMAL,                    /* file attribute         */
  8796.      FILE_CREATE,                    /* create the file        */
  8797.      OPEN_ACCESS_WRITEONLY | OPEN_SHARE_DENYNONE, /* open mode */
  8798.      0L);                            /* reserved               */
  8799.  
  8800.  
  8801.  
  8802.  
  8803.  
  8804.  See Also
  8805.  
  8806.  DosBufReset, DosClose, DosDevIOCtl, DosOpen2, DosDupHandle, DosQFHandState,
  8807.  DosQFileInfo, DosQFileMode, DosQFSInfo, DosSetFHandState, DosSetFileMode,
  8808.  DosWrite
  8809.  
  8810.  
  8811.  Changes
  8812.  
  8813.  The following constants are new for the fsOpenMode parameter:
  8814.  
  8815.  Value                             Meaning
  8816.  ────────────────────────────────────────────────────────────────────────────
  8817.  
  8818.  OPEN_FLAGS_NO_LOCALITY            There is no specific information
  8819.                                    regarding the locality of reference (the
  8820.                                    degree of randomness with which the file
  8821.                                    is accessed).
  8822.  
  8823.  OPEN_FLAGS_SEQUENTIAL             The file is accessed sequentially.
  8824.  
  8825.  OPEN_FLAGS_RANDOM                 The file is accessed randomly.
  8826.  
  8827.  OPEN_FLAGS_RANDOMSEQUENTIAL       The file is accessed randomly, but there
  8828.                                    is a degree of sequential I/O within
  8829.                                    that random access. For example, this
  8830.                                    flag is specified if large blocks of
  8831.                                    data are to be read or written at random
  8832.                                    locations in the file.
  8833.  
  8834.  OPEN_FLAGS_NO_CACHE               The disk drive should not cache data in
  8835.                                    I/O operations on this file.
  8836.  
  8837.  
  8838.  
  8839.  Corrections
  8840.  
  8841.  The comments incorrectly stated that ERROR_ACCESS_DENIED would be returned
  8842.  if another process had previously opened the file in an incompatible mode.
  8843.  The correct error code is ERROR_SHARING_VIOLATION.
  8844.  
  8845.  The Category 8 functions DSK_READTRACK and DSK_WRITETRACK are not supported
  8846.  in MS-DOS versions 3.x and 4.x. You cannot use the DosOpen function to read
  8847.  or write to a track when you are running MS-DOS.
  8848.  
  8849.  
  8850.  █    DosOpen2
  8851.  ────────────────────────────────────────────────────────────────────────────
  8852.  
  8853.  USHORT DosOpen2  (pszFileName, phfHand, pusAction, ulFileSize, usAttribute,
  8854.  usOpenFlags, ulOpenMode, peaop, ulReserved)
  8855.  
  8856.  PSZ  pszFileName;                 /*pointer to filename */
  8857.  
  8858.  PHFILE  phfHand;                  /*pointer to variable for file handle */
  8859.  
  8860.  PUSHORT  pusAction;               /*pointer to variable for action taken
  8861.                                    */
  8862.  
  8863.  ULONG  ulFileSize;                /*file size if file is created or
  8864.                                    truncated */
  8865.  
  8866.  USHORT  usAttribute;              /*file attribute */
  8867.  
  8868.  USHORT  usOpenFlags;              /*action if file exists/does not exist
  8869.                                    */
  8870.  
  8871.  ULONG  ulOpenMode;                /*open mode of file */
  8872.  
  8873.  PEAOP  peaop;                     /*pointer to structure for extended
  8874.                                    attributes */
  8875.  
  8876.  ULONG  ulReserved;                /*must be zero */
  8877.  
  8878.  
  8879.  The DosOpen2 function opens an existing file or creates a new file. This
  8880.  function returns a handle that can be used to read from and write to the
  8881.  file, as well as to retrieve information about the file.
  8882.  
  8883.  For compatibility with future versions of MS OS/2, the DosOpen2 function
  8884.  should be used instead of the DosOpen function.
  8885.  
  8886.  
  8887.  Parameters
  8888.  
  8889.  pszFileName  Points to the null-terminated string that specifies the name of
  8890.  the file to be opened. The string must be a valid MS OS/2 filename and must
  8891.  not contain wildcard characters.
  8892.  
  8893.  phfHand  Points to the variable that receives the handle of the opened file.
  8894.  
  8895.  
  8896.  pusAction  Points to the variable receiving the value that specifies the
  8897.  action taken by the DosOpen2 function. If DosOpen2 fails, this value has no
  8898.  meaning. Otherwise, it is one of the following values:
  8899.  
  8900.  Value                             Meaning
  8901.  ────────────────────────────────────────────────────────────────────────────
  8902.  
  8903.  FILE_CREATED                      File was created.
  8904.  
  8905.  FILE_EXISTED                      File already existed.
  8906.  
  8907.  FILE_TRUNCATED                    File existed and was truncated.
  8908.  
  8909.  
  8910.  
  8911.  ulFileSize  Specifies the file's new size (in bytes). The size specification
  8912.  has no effect on a file that is opened only for reading.
  8913.  
  8914.  usAttribute  Specifies the file attributes. This parameter can be a
  8915.  combination of the following values:
  8916.  
  8917.  Value                             Meaning
  8918.  ────────────────────────────────────────────────────────────────────────────
  8919.  
  8920.  FILE_NORMAL                       File can be read from or written to.
  8921.  
  8922.  FILE_READONLY                     File can be read from, but not written
  8923.                                    to.
  8924.  
  8925.  FILE_HIDDEN                       File is hidden and does not appear in a
  8926.                                    directory listing.
  8927.  
  8928.  FILE_SYSTEM                       File is a system file.
  8929.  
  8930.  FILE_ARCHIVED                     File has been archived.
  8931.  
  8932.  
  8933.  
  8934.  File attributes apply only if the file is created.
  8935.  
  8936.  usOpenFlags  Specifies the action to take both when the file exists and when
  8937.  it does not exist. This parameter can be one of the following values:
  8938.  
  8939.  Value                             Meaning
  8940.  ────────────────────────────────────────────────────────────────────────────
  8941.  
  8942.  FILE_CREATE                       Create a new file; fail if the file
  8943.                                    already exists.
  8944.  
  8945.  FILE_OPEN                         Open an existing file; fail if the file
  8946.                                    does not exist.
  8947.  
  8948.  FILE_OPEN | FILE_CREATE           Open an existing file, or create the
  8949.                                    file if it does not exist.
  8950.  
  8951.  FILE_TRUNCATE                     Open an existing file and change its
  8952.                                    size to a given size.
  8953.  
  8954.  FILE_TRUNCATE | FILE_CREATE       Open an existing file and truncate it,
  8955.                                    or create the file if it does not exist.
  8956.  
  8957.  
  8958.  
  8959.  ulOpenMode  Specifies the modes with which to open the file. This parameter
  8960.  consists of one access mode and one share mode. All other values are
  8961.  optional; one locality mode can be specified; and the other values can be
  8962.  given in any combination:
  8963.  
  8964.  Value                             Meaning
  8965.  ────────────────────────────────────────────────────────────────────────────
  8966.  
  8967.  OPEN_ACCESS_READONLY              Data can be read from the file but not
  8968.                                    written to it.
  8969.  
  8970.  OPEN_ACCESS_READWRITE             Data can be read from or written to the
  8971.                                    file.
  8972.  
  8973.  OPEN_ACCESS_WRITEONLY             Data can be written to the file but not
  8974.                                    read from it.
  8975.  
  8976.  OPEN_SHARE_DENYNONE               Other processes can open the file for
  8977.                                    any access: read-only, write-only, or
  8978.                                    read-write.
  8979.  
  8980.  OPEN_SHARE_DENYREAD               Other processes can open the file for
  8981.                                    write-only access, but they cannot open
  8982.                                    it for read-only or read-write access.
  8983.  
  8984.  OPEN_SHARE_DENYREADWRITE          The current process has exclusive access
  8985.                                    to the file. No process (including the
  8986.                                    current process) can open the file.
  8987.  
  8988.  OPEN_SHARE_DENYWRITE              Other processes can open the file for
  8989.                                    read-only access, but they cannot open
  8990.                                    it for write-only or read-write access.
  8991.  
  8992.  OPEN_FLAGS_DASD                   The file handle represents a physical
  8993.                                    drive that has been opened for direct
  8994.                                    access. (The pszFileName parameter must
  8995.                                    specify a drive name.) The DosDevIOCtl
  8996.                                    function can be used with this file
  8997.                                    handle to bypass the file system and to
  8998.                                    access the sectors of the drive directly.
  8999.  
  9000.  OPEN_FLAGS_FAIL_ON_ERROR          Any function that uses the file handle
  9001.                                    returns immediately with an error value
  9002.                                    if there is an I/O error─for example,
  9003.                                    when the drive door is open or a sector
  9004.                                    is missing. If this value is not
  9005.                                    specified, the system passes the error
  9006.                                    to the system critical-error handler,
  9007.                                    which then reports the error to the user
  9008.                                    with a hard-error pop-up message. The
  9009.                                    fail-on-error flag is not inherited by
  9010.                                    child processes. The fail-on-error flag
  9011.                                    applies to all functions that use the
  9012.                                    file handle, with the exception of the
  9013.                                    DosDevIOCtl function.
  9014.  
  9015.  OPEN_FLAGS_NOINHERIT              The file handle is not available to any
  9016.                                    child process started by the current
  9017.                                    process. If this value is not specified,
  9018.                                    any child process started by the current
  9019.                                    process can use the file handle.
  9020.  
  9021.  OPEN_FLAGS_WRITE_THROUGH          This flag applies to functions (for
  9022.                                    example, DosWrite) that write data to
  9023.                                    the file. If this value is specified,
  9024.                                    the system writes data to the device
  9025.                                    before the given function returns.
  9026.                                    Otherwise, the system can store the data
  9027.                                    in a buffer and write the data to the
  9028.                                    device only when the buffer is full or
  9029.                                    the file is closed.
  9030.  
  9031.  OPEN_FLAGS_NO_LOCALITY            There is no specific information
  9032.                                    regarding the locality of reference (the
  9033.                                    degree of randomness with which the file
  9034.                                    is accessed).
  9035.  
  9036.  OPEN_FLAGS_SEQUENTIAL             The file is accessed sequentially.
  9037.  
  9038.  OPEN_FLAGS_RANDOM                 The file is accessed randomly.
  9039.  
  9040.  OPEN_FLAGS_RANDOMSEQUENTIAL       The file is accessed randomly, but there
  9041.                                    is a degree of sequential I/O within
  9042.                                    that random access. For example, this
  9043.                                    flag is specified if large blocks of
  9044.                                    data are to be read or written at random
  9045.                                    locations in the file.
  9046.  
  9047.  OPEN_FLAGS_NO_CACHE               The disk driver should not cache data in
  9048.                                    I/O operations on this file.
  9049.  
  9050.  
  9051.  
  9052.  peaop  Points to an EAOP structure that defines extended attributes for the
  9053.  file. If this value is NULL, the file will not use extended attributes.
  9054.  Before you call the DosOpen2 function, the fpFEAList field of the EAOP
  9055.  structure must point to a data area where the relevant extended-attribute
  9056.  information is stored. The EAOP structure has the following form:
  9057.  
  9058.  typedef struct _EAOP {
  9059.      PGEALIST fpGEAList;
  9060.      PFEALIST fpFEAList;
  9061.      ULONG    oError;
  9062.  } EAOP;
  9063.  
  9064.  
  9065.  
  9066.  
  9067.  For a full description, see Chapter 4, "Types, Macros, Structures."
  9068.  
  9069.  ulReserved  Specifies a reserved value; must be zero.
  9070.  
  9071.  
  9072.  Return Value
  9073.  
  9074.  The return value is zero if the function is successful. Otherwise, it is an
  9075.  error value, which may be one of the following:
  9076.  
  9077.       ERROR_ACCESS_DENIED
  9078.       ERROR_CANNOT_MAKE
  9079.       ERROR_DISK_FULL
  9080.       ERROR_DRIVE_LOCKED
  9081.       ERROR_EA_LIST_INCONSISTENT
  9082.       ERROR_EA_VALUE_UNSUPPORTABLE
  9083.       ERROR_FILE_NOT_FOUND
  9084.       ERROR_FILENAME_EXCED_RANGE
  9085.       ERROR_INVALID_ACCESS
  9086.       ERROR_INVALID_EA_NAME
  9087.       ERROR_INVALID_PARAMETER
  9088.       ERROR_NOT_DOS_DISK
  9089.       ERROR_OPEN_FAILED
  9090.       ERROR_PATH_NOT_FOUND
  9091.       ERROR_SHARING_BUFFER_EXCEEDED
  9092.       ERROR_SHARING_VIOLATION
  9093.       ERROR_TOO_MANY_OPEN_FILES
  9094.  
  9095.  
  9096.  
  9097.  
  9098.  
  9099.  Comments
  9100.  
  9101.  The read/write pointer is initially set at the first byte of the file.
  9102.  
  9103.  The ulFileSize parameter affects the size of the file only when it is
  9104.  created, truncated, or replaced. The value specified for this parameter is
  9105.  the recommended file size. The file can be opened even if allocation of the
  9106.  full number of bytes fails.
  9107.  
  9108.  The value of the usOpenFlags parameter provides a disk-access mechanism that
  9109.  is independent of the file system. When this value is used, the DosOpen2
  9110.  function returns a handle to the calling process that represents the
  9111.  physical drive as a file. In order to prevent other processes from accessing
  9112.  the disk, the calling process must also issue a DosDevIOCtl DSK_LOCKDRIVE
  9113.  subcall, which requires the file handle returned by the DosOpen2 function
  9114.  for the physical drive.
  9115.  
  9116.  Extended attributes that require contiguous disk space may cause the
  9117.  function to fail if the file system is unable to allocate contiguous space.
  9118.  
  9119.  DosOpen2 sets extended attributes when a file is created, replaced, or
  9120.  truncated. Extended attributes are ordinarily set when a file is opened for
  9121.  reading. When a file is replaced, the extended attributes are also replaced.
  9122.  Extended attributes are discarded if the peaop parameter is NULL.
  9123.  
  9124.  The pszFileName parameter cannot point to a volume label, because volume
  9125.  labels cannot be opened.
  9126.  
  9127.  Any sharing restrictions placed on a file when it is opened are removed when
  9128.  it is closed. When a file is inherited by a child process, all sharing and
  9129.  access restrictions are also inherited.
  9130.  
  9131.  The DosOpen2 function can be used to open the client end of a named pipe and
  9132.  return a handle of the pipe. The pipe must be in "listen" state for the open
  9133.  operation to succeed; otherwise the open operation fails and the
  9134.  ERROR_PIPE_BUSY error value is returned. Until a given instance of a named
  9135.  pipe has been closed by a client, that same instance cannot be opened by
  9136.  another client; however, the opening process can duplicate the open handle
  9137.  as many times as required. The access and sharing modes specified when a
  9138.  pipe is opened must be consistent with the modes specified in the call to
  9139.  the DosMakeNmPipe function. Pipes are always opened with the pipe-specific
  9140.  states set to lock read and write operations and are read as a byte stream.
  9141.  
  9142.  
  9143.  See Also
  9144.  
  9145.  DosClose, DosDevIOCtl, DosDupHandle, DosMakeNmPipe, DosOpen,
  9146.  DosSetFHandState, DosSetFileInfo
  9147.  
  9148.  
  9149.  █    DosQFHandState
  9150.  ────────────────────────────────────────────────────────────────────────────
  9151.  
  9152.  USHORT DosQFHandState  (hf, pfsOpenMode)
  9153.  
  9154.  HFILE  hf;                        /*file handle */
  9155.  
  9156.  PUSHORT  pfsOpenMode;             /*pointer to variable for file-handle
  9157.                                    state */
  9158.  
  9159.  
  9160.  The DosQFHandState function retrieves the state of the specified file
  9161.  handle. The file-handle state indicates whether the file may be read from or
  9162.  written to and whether it may be opened for reading or writing by other
  9163.  processes.
  9164.  
  9165.  The DosQFHandState function is a family API function.
  9166.  
  9167.  
  9168.  Parameters
  9169.  
  9170.  hf  Identifies the file whose file-handle state is to be retrieved. This
  9171.  handle must have been previously created by using the DosOpen function.
  9172.  
  9173.  pfsOpenMode  Points to the variable that receives the file-handle state. The
  9174.  file-handle state consists of one access mode, one share mode, and optional
  9175.  flags. It is identical to the values specified in the fsOpenMode parameter
  9176.  of the DosOpen function. Which values are set can be determined by using the
  9177.  AND operator to combine the value returned in the pfsOpenMode parameter with
  9178.  one or more of the following values:
  9179.  
  9180.  Value                             Meaning
  9181.  ────────────────────────────────────────────────────────────────────────────
  9182.  
  9183.  OPEN_ACCESS_READONLY              Data can be read from the file but not
  9184.                                    written to it.
  9185.  
  9186.  OPEN_ACCESS_READWRITE             Data can be read from or written to the
  9187.                                    file.
  9188.  
  9189.  OPEN_ACCESS_WRITEONLY             Data can be written to the file but not
  9190.                                    read from it.
  9191.  
  9192.  OPEN_SHARE_DENYNONE               Other processes can open the file for
  9193.                                    any access: read-only, write-only, or
  9194.                                    read-write.
  9195.  
  9196.  OPEN_SHARE_DENYREAD               Other processes can open the file for
  9197.                                    write-only access but not for read-only
  9198.                                    or read-write access. .
  9199.  
  9200.  OPEN_SHARE_DENYREADWRITE          The current process has exclusive access
  9201.                                    to the file.
  9202.  
  9203.  OPEN_SHARE_DENYWRITE              Other processes can open the file for
  9204.                                    read-only access but not for write-only
  9205.                                    or read-write access. .
  9206.  
  9207.  OPEN_FLAGS_DASD                   The file handle represents a physical
  9208.                                    drive that has been opened for direct
  9209.                                    access.
  9210.  
  9211.  OPEN_FLAGS_FAIL_ON_ERROR          Any function that uses the file handle
  9212.                                    returns immediately with an error code
  9213.                                    if there is an I/O error.
  9214.  
  9215.  OPEN_FLAGS_NOINHERIT              The file handle is private to the
  9216.                                    current process.
  9217.  
  9218.  OPEN_FLAGS_WRITE_THROUGH          The system writes data to the device
  9219.                                    before the given function returns.
  9220.  
  9221.  OPEN_FLAGS_NO_CACHE               The system does not cache file data.
  9222.  
  9223.  
  9224.  
  9225.  Return Value
  9226.  
  9227.  The return value is zero if the function is successful. Otherwise, it is an
  9228.  error value, which may be the following:
  9229.  
  9230.       ERROR_INVALID_HANDLE
  9231.  
  9232.  
  9233.  
  9234.  
  9235.  
  9236.  Example
  9237.  
  9238.  The example on the following page calls the DosQFHandState function by using
  9239.  the handle of a previously opened file, and then checks the variable
  9240.  fsOpenMode and reports whether the file is open for read/write access:
  9241.  
  9242.  HFILE hf;
  9243.  USHORT fsOpenMode;
  9244.      .
  9245.      .
  9246.      .
  9247.  DosQFHandState(hf, &fsOpenMode);
  9248.  if (fsOpenMode & OPEN_ACCESS_READWRITE)
  9249.      VioWrtTTY("File opened for read/write access\r\n", 35, 0);
  9250.  if (fsOpenMode & OPEN_SHARE_DENYREADWRITE)
  9251.      VioWrtTTY("File cannot be shared\r\n", 23, 0);
  9252.  
  9253.  
  9254.  
  9255.  
  9256.  
  9257.  See Also
  9258.  
  9259.  DosDevIOCtl, DosExecPgm, DosOpen, DosSetFHandState
  9260.  
  9261.  
  9262.  Changes
  9263.  
  9264.  The OPEN_FLAGS_NO_CACHE value can be specified for the pfsOpenMode
  9265.  parameter. If specified, the system does not cache file data.
  9266.  
  9267.  
  9268.  █    DosQFileInfo
  9269.  ────────────────────────────────────────────────────────────────────────────
  9270.  
  9271.  USHORT DosQFileInfo  (hf, usInfoLevel, pvInfo, cbInfoBuf)
  9272.  
  9273.  HFILE  hf;                        /*handle of file about which data is
  9274.                                    sought */
  9275.  
  9276.  USHORT  usInfoLevel;              /*level of file data required */
  9277.  
  9278.  PVOID  pvInfo;                    /*pointer to file-data buffer */
  9279.  
  9280.  USHORT  cbInfoBuf;                /*length of file-data buffer */
  9281.  
  9282.  
  9283.  The DosQFileInfo function retrieves information about a specific file. The
  9284.  file information consists of the date and time the file was created, the
  9285.  date and time it was last accessed, the date and time it was last written
  9286.  to, the size of the file, and its attributes. It can also be used to return
  9287.  information about the extended attributes used for a file.
  9288.  
  9289.  The file information is based on the most recent call to the DosClose or the
  9290.  DosBufReset function.
  9291.  
  9292.  The DosQFileInfo function is a family API function.
  9293.  
  9294.  
  9295.  Parameters
  9296.  
  9297.  hf  Identifies the file about which information is to be retrieved. This
  9298.  handle must have been created by using the DosOpen function.
  9299.  
  9300.  usInfoLevel  Specifies the level of file information required. It may be one
  9301.  of the following values:
  9302.  
  9303.  Value                             Meaning
  9304.  ────────────────────────────────────────────────────────────────────────────
  9305.  
  9306.  FIL_STANDARD                      This will return a FILESTATUS structure.
  9307.                                    Any time and data fields in the
  9308.                                    structure that the file-system device
  9309.                                    does not support are set to zero.
  9310.  
  9311.  FIL_QUERYEASIZE                   This will return a FILESTATUS2 structure,
  9312.                                    which contains the same information as
  9313.                                    FILESTATUS plus the size of the
  9314.                                    structure used by the
  9315.                                    FIL_QUERYEASFROMLIST value (for MS OS/2
  9316.                                    versions 1.2 and later, this size cannot
  9317.                                    exceed 65,535 bytes).
  9318.  
  9319.  FIL_QUERYEASFROMLIST              This will return an EAOP structure that
  9320.                                    contains a subset of the file's
  9321.                                    extended-attribute information.
  9322.  
  9323.  
  9324.  
  9325.  pvInfo  Points to the structure that receives the file information. This
  9326.  struc- ture will be FILESTATUS for FIL_STANDARD information, FILESTATUS2 for
  9327.  FIL_QUERYEASIZE information, and EAOP for FIL_QUERYEASFROMLIST information.
  9328.  
  9329.  The FILESTATUS structure has the following form:
  9330.  
  9331.  typedef struct _FILESTATUS {
  9332.      FDATE  fdateCreation;
  9333.      FTIME  ftimeCreation;
  9334.      FDATE  fdateLastAccess;
  9335.      FTIME  ftimeLastAccess;
  9336.      FDATE  fdateLastWrite;
  9337.      FTIME  ftimeLastWrite;
  9338.      ULONG  cbFile;
  9339.      ULONG  cbFileAlloc;
  9340.      USHORT attrFile;
  9341.  } FILESTATUS;
  9342.  
  9343.  
  9344.  
  9345.  
  9346.  The FILESTATUS2 structure has the following form:
  9347.  
  9348.  typedef struct _FILESTATUS2 {
  9349.      FDATE  fdateCreation;
  9350.      FTIME  ftimeCreation;
  9351.      FDATE  fdateLastAccess;
  9352.      FTIME  ftimeLastAccess;
  9353.      FDATE  fdateLastWrite;
  9354.      FTIME  ftimeLastWrite;
  9355.      ULONG  cbFile;
  9356.      ULONG  cbFileAlloc;
  9357.      USHORT attrFile;
  9358.      USHORT cbList;
  9359.  } FILESTATUS2;
  9360.  
  9361.  
  9362.  
  9363.  
  9364.  The EAOP structure has the following form:
  9365.  
  9366.  typedef struct _EAOP {
  9367.      PGEALIST fpGEAList;
  9368.      PFEALIST fpFEAList;
  9369.      ULONG  oError;
  9370.  } EAOP;
  9371.  
  9372.  
  9373.  
  9374.  
  9375.  For a full description, see Chapter 4, "Types, Macros, Structures."
  9376.  
  9377.  cbInfoBuf  Specifies the length (in bytes) of the buffer that receives the
  9378.  file information.
  9379.  
  9380.  
  9381.  Return Value
  9382.  
  9383.  The return value is zero if the function is successful. Otherwise, it is an
  9384.  error value, which may be one of the following:
  9385.  
  9386.       ERROR_INVALID_EA_NAME
  9387.       ERROR_EA_LIST_INCONSISTENT
  9388.       ERROR_BUFFER_OVERFLOW
  9389.       ERROR_DIRECT_ACCESS_HANDLE
  9390.       ERROR_INVALID_HANDLE
  9391.       ERROR_INVALID_LEVEL
  9392.  
  9393.  
  9394.  
  9395.  
  9396.  
  9397.  Comments
  9398.  
  9399.  Prior to the function being called, the fpFEAlist field in the EAOP
  9400.  structure should be initialized so that it points to the FEALIST structure
  9401.  that contains the relevant FEA structure. The cbList field in the FEALIST
  9402.  structure is valid, giving the size of the FEA structure.
  9403.  
  9404.  If the FEALIST structure is not large enough to hold the returned
  9405.  information (indicated by ERROR_BUFFER_OVERFLOW), cbList will still be
  9406.  valid, assuming there is at least enough space for it. Its value will be the
  9407.  size of the entire set of extended attributes for the file, even if only a
  9408.  subset of attributes was requested.
  9409.  
  9410.  
  9411.  Example
  9412.  
  9413.  This example opens the file abc, calls the DosQFileInfo function to retrieve
  9414.  the current allocated size, and then calls the DosNewSize function to
  9415.  increase the file's size by 1K:
  9416.  
  9417.  HFILE hf;
  9418.  USHORT usAction;
  9419.  FILESTATUS fstsFile;
  9420.  DosOpen("abc", &hf, &usAction, 0L, FILE_NORMAL,
  9421.      FILE_OPEN | FILE_CREATE,
  9422.      OPEN_ACCESS_WRITEONLY | OPEN_SHARE_DENYNONE, 0L);
  9423.  DosQFileInfo(hf,                 /* file handle                 */
  9424.      FIL_STANDARD,                /* level of information        */
  9425.      &fstsFile,                   /* address of file-data buffer */
  9426.      sizeof(fstsFile));           /* size of data buffer         */
  9427.  DosNewSize(hf, fstsFile.cbFileAlloc + 1024L);
  9428.  
  9429.  
  9430.  
  9431.  
  9432.  
  9433.  See Also
  9434.  
  9435.  DosBufReset, DosClose, DosNewSize, DosOpen, DosQFileMode, DosQPathInfo,
  9436.  DosSetFileInfo
  9437.  
  9438.  
  9439.  Changes
  9440.  
  9441.  Parameters and structures for FIL_QUERYEASIZE and FIL_QUERYEASFROMLIST
  9442.  information have been added. The type of the pvInfo parameter has changed
  9443.  from PFILESTATUS to PVOID because one of three structures can be used for
  9444.  this parameter.
  9445.  
  9446.  
  9447.  █    DosQFSAttach
  9448.  ────────────────────────────────────────────────────────────────────────────
  9449.  
  9450.  USHORT DosQFSAttach  (pszDev, usOrdinal, usInfoLevel, pFSAttBuf, pcbAttBuf,
  9451.  ulReserved)
  9452.  
  9453.  PSZ  pszDev;                      /*pointer to drive or device */
  9454.  
  9455.  USHORT  usOrdinal;                /*index to drive or device */
  9456.  
  9457.  USHORT  usInfoLevel;              /*level of information */
  9458.  
  9459.  PBYTE  pFSAttBuf;                 /*pointer to structure for file-system
  9460.                                    attributes */
  9461.  
  9462.  PUSHORT  pcbAttBuf;               /*pointer to structure length */
  9463.  
  9464.  ULONG  ulReserved;                /*must be zero */
  9465.  
  9466.  
  9467.  The DosQFSAttach function queries information about an attached remote file
  9468.  system or a local file system. The function can also query information about
  9469.  a character device or pseudo-character device attached to a local or remote
  9470.  file system.
  9471.  
  9472.  
  9473.  Parameters
  9474.  
  9475.  pszDev  Points to a null-terminated string that specifies the drive letter
  9476.  followed by a colon or to the name of a character or pseudo-character
  9477.  device. If this parameter is a character or pseudo-character device name,
  9478.  the format of the string is \edevice\efilename, where filename is a valid MS
  9479.  OS/2 filename. This parameter is ignored if the usInfoLevel parameter is set
  9480.  to either FSAIL_DEVNUMBER or FSAIL_DRVNUMBER.
  9481.  
  9482.  usOrdinal  Specifies an index into the list of character or pseudo-character
  9483.  devices or the set of drives. The first item in the list is always 1. This
  9484.  parameter is ignored if the usInfoLevel parameter is set to FSAIL_QUERYNAME.
  9485.  
  9486.  
  9487.  usInfoLevel  Specifies the type of information requested. This parameter can
  9488.  be one of the following values:
  9489.  
  9490.  Value                             Meaning
  9491.  ────────────────────────────────────────────────────────────────────────────
  9492.  
  9493.  FSAIL_QUERYNAME                   Returns information about the drive or
  9494.                                    device pointed to by the pszDev
  9495.                                    parameter. When this value is specified,
  9496.                                    the usOrdinal parameter is ignored.
  9497.  
  9498.  FSAIL_DEVNUMBER                   Returns information about the character
  9499.                                    or pseudo-character device specified by
  9500.                                    the usOrdinal parameter. When this value
  9501.                                    is specified, the pszDev parameter is
  9502.                                    ignored.
  9503.  
  9504.  FSAIL_DRVNUMBER                   Returns information about the drive
  9505.                                    specified by the usOrdinal parameter.
  9506.                                    When this value is specified, the pszDev
  9507.                                    parameter is ignored.
  9508.  
  9509.  
  9510.  
  9511.  pFSAttBuf  Points to the buffer that receives information about the file
  9512.  system. The buffer is organized as a FSQBUFFER structure. Because the name
  9513.  fields can vary in length, however, the structure cannot be used directly to
  9514.  retrieve the data. The FSQBUFFER structure has the following form:
  9515.  
  9516.  typedef struct _FSQBUFFER {
  9517.      USHORT  iType;
  9518.      USHORT  cbName;
  9519.      UCHAR   szName[1];
  9520.      USHORT  cbFSDName;
  9521.      UCHAR   szFSDName[1];
  9522.      USHORT  cbFSAData;
  9523.      UCHAR   rgFSAData[1];
  9524.  } FSQBUFFER;
  9525.  
  9526.  
  9527.  
  9528.  
  9529.  For a full description, see Chapter 4, "Types, Macros, Structures."
  9530.  
  9531.  pcbAttBuf  Points to a variable. When this function is called, the variable
  9532.  specifies the length of the buffer pointed to by the pFSAttBuf parameter.
  9533.  When the function returns, this variable contains the length of the data
  9534.  copied to the pFSAttBuf buffer.
  9535.  
  9536.  ulReserved  Specifies a reserved value; must be zero.
  9537.  
  9538.  
  9539.  Return Value
  9540.  
  9541.  The return value is zero if the function is successful. Otherwise, it is an
  9542.  error value, which may be one of the following:
  9543.  
  9544.       ERROR_BUFFER_OVERFLOW
  9545.       ERROR_INVALID_DRIVE
  9546.       ERROR_INVALID_LEVEL
  9547.       ERROR_NO_MORE_ITEMS
  9548.  
  9549.  
  9550.  
  9551.  
  9552.  
  9553.  Comments
  9554.  
  9555.  The DosQFSAttach function can be used to ensure that the correct file system
  9556.  is loaded for a disk. Without this information, there is potential for the
  9557.  data on the disk to be destroyed because the wrong file system could be
  9558.  attached to the disk by default.
  9559.  
  9560.  
  9561.  Example
  9562.  
  9563.  This example calls DosQFSAttach to get information about drive C, and then
  9564.  displays the device and file-system names:
  9565.  
  9566.  PSZ psz;
  9567.  PUSHORT pcb;
  9568.  USHORT cb;
  9569.  SEL sel;
  9570.  
  9571.  DosAllocSeg(1024, &sel, SEG_NONSHARED); /* allocates buffer               */
  9572.  
  9573.  if (!DosQFSAttach("c:", 0, FSAIL_QUERYNAME, MAKEP(sel, 0), &cb, 0L)) {
  9574.      pcb = MAKEP(sel, 2);               /* points to length of device name */
  9575.      psz = MAKEP(sel, 4);               /* points to device name           */
  9576.      VioWrtTTY(psz, *pcb, (HVIO) NULL); /* displays device name     */
  9577.      VioWrtTTY("\r\n", 2, 0L);
  9578.      psz += *pcb + 3;              /* adds null char. and name-length var. */
  9579.      pcb = (PUSHORT) (psz - 2);    /* points to length of name             */
  9580.      VioWrtTTY(psz, *pcb, (HVIO) NULL); /* displays file-system name       */
  9581.      VioWrtTTY("\r\n", 2, 0L);
  9582.  }
  9583.  
  9584.  
  9585.  
  9586.  
  9587.  
  9588.  See Also
  9589.  
  9590.  DosFSAttach, DosQFSInfo
  9591.  
  9592.  
  9593.  █    DosQNmPipeInfo
  9594.  ────────────────────────────────────────────────────────────────────────────
  9595.  
  9596.  USHORT DosQNmPipeInfo  (hp, usInfoLevel, pbBuf, cbBuf)
  9597.  
  9598.  HPIPE  hp;                        /*pipe handle */
  9599.  
  9600.  USHORT  usInfoLevel;              /*level of information to retrieve */
  9601.  
  9602.  PBYTE  pbBuf;                     /*pointer to buffer for information */
  9603.  
  9604.  USHORT  cbBuf;                    /*number of bytes in buffer */
  9605.  
  9606.  
  9607.  The DosQNmPipeInfo function retrieves information about a named pipe.
  9608.  
  9609.  
  9610.  Parameters
  9611.  
  9612.  hp  Identifies the pipe to read from.
  9613.  
  9614.  usInfoLevel  Specifies the level of information to retrieve. Level 1 is
  9615.  miscellaneous information about the pipe.
  9616.  
  9617.  pbBuf  Points to the buffer that receives the information. For level-1
  9618.  information, the data is stored in the PIPEINFO structure. The PIPEINFO
  9619.  structure has the following form:
  9620.  
  9621.  typedef struct _PIPEINFO {
  9622.      USHORT cbOut;
  9623.      USHORT cbIn;
  9624.      BYTE   cbMaxInst;
  9625.      BYTE   cbCurInst;
  9626.      BYTE   cbName;
  9627.      CHAR   szName[1];
  9628.  } PIPEINFO;
  9629.  
  9630.  
  9631.  
  9632.  
  9633.  For more information, see Chapter 4, "Types, Macros, Structures."
  9634.  
  9635.  cbBuf  Specifies the size (in bytes) of the buffer receiving the
  9636.  information.
  9637.  
  9638.  
  9639.  Return Value
  9640.  
  9641.  The return value is zero if the function is successful. Otherwise, it is an
  9642.  error value, which may be one of the following:
  9643.  
  9644.       ERROR_BAD_PIPE
  9645.       ERROR_BUFFER_OVERFLOW
  9646.       ERROR_INVALID_LEVEL
  9647.       ERROR_INVALID_PARAMETER
  9648.       ERROR_PIPE_NOT_CONNECTED
  9649.  
  9650.  
  9651.  
  9652.  
  9653.  
  9654.  Comments
  9655.  
  9656.  For level-1 information, if the pipe name is longer than 255 bytes, zero
  9657.  will be returned in the cbName field of the PIPEINFO structure. The full
  9658.  null-terminated string that contains the name will be returned in the
  9659.  location specified by the szName field.
  9660.  
  9661.  
  9662.  See Also
  9663.  
  9664.  DosQNmPHandState, DosQNmPipeSemState
  9665.  
  9666.  
  9667.  Changes
  9668.  
  9669.  Pipe names longer than 255 bytes are now supported. For names longer than
  9670.  255 bytes, however, zero is returned in the cbName field of the PIPEINFO
  9671.  structure.
  9672.  
  9673.  
  9674.  Corrections
  9675.  
  9676.  This function returns only level-1 information. Erroneous references to
  9677.  level-2 information have been removed.
  9678.  
  9679.  
  9680.  █    DosQNmPipeSemState
  9681.  ────────────────────────────────────────────────────────────────────────────
  9682.  
  9683.  USHORT DosQNmPipeSemState  (hsem, pnmpsmst, cbBuf)
  9684.  
  9685.  HSEM  hsem;                       /*semaphore handle */
  9686.  
  9687.  PPIPESEMSTATE  pnmpsmst;          /*pointer to buffer receiving
  9688.                                    information */
  9689.  
  9690.  USHORT  cbBuf;                    /*buffer size */
  9691.  
  9692.  
  9693.  The DosQNmPipeSemState function returns information about all local named
  9694.  pipes that are in blocking mode and are associated with a specified system
  9695.  semaphore.
  9696.  
  9697.  
  9698.  Parameters
  9699.  
  9700.  hsem  Identifies the semaphore that is associated with the named pipe.
  9701.  
  9702.  pnmpsmst  Points to the PIPESEMSTATE structure that receives the
  9703.  information. The PIPESEMSTATE structure has the following form:
  9704.  
  9705.  typedef struct _PIPESEMSTATE {
  9706.      BYTE   fStatus;
  9707.      BYTE   fFlag;
  9708.      USHORT usKey;
  9709.      USHORT usAvail;
  9710.  } PIPESEMSTATE;
  9711.  
  9712.  
  9713.  
  9714.  
  9715.  For a full description, see Chapter 4, "Types, Macros, Structures."
  9716.  
  9717.  cbBuf  Specifies the length (in bytes) of the structure that receives the
  9718.  information. Programs written in the C language should use the sizeof
  9719.  operator to set this parameter.
  9720.  
  9721.  
  9722.  Return Value
  9723.  
  9724.  The return value is zero if the function is successful. Otherwise, it is an
  9725.  error value, which may be one of the following:
  9726.  
  9727.       ERROR_INVALID_PARAMETER
  9728.       ERROR_SEM_NOT_FOUND
  9729.  
  9730.  
  9731.  
  9732.  
  9733.  
  9734.  See Also
  9735.  
  9736.  DosSetNmPipeSem
  9737.  
  9738.  
  9739.  Corrections
  9740.  
  9741.  The second parameter has been replaced by a PIPESEMSTATE structure.
  9742.  
  9743.  
  9744.  █    DosQPathInfo
  9745.  ────────────────────────────────────────────────────────────────────────────
  9746.  
  9747.  USHORT DosQPathInfo  (pszPath, usInfoLevel, pInfoBuf, cbInfoBuf, ulReserved)
  9748.  
  9749.  PSZ  pszPath;                     /*pointer to path */
  9750.  
  9751.  USHORT  usInfoLevel;              /*level of information */
  9752.  
  9753.  PBYTE  pInfoBuf;                  /*pointer to buffer for information */
  9754.  
  9755.  USHORT  cbInfoBuf;                /*length of information buffer */
  9756.  
  9757.  ULONG  ulReserved;                /*must be zero */
  9758.  
  9759.  
  9760.  The DosQPathInfo function returns information about a specified file or
  9761.  directory.
  9762.  
  9763.  The DosQPathInfo function is a family API function.
  9764.  
  9765.  
  9766.  Parameters
  9767.  
  9768.  pszPath  Points to the null-terminated string that specifies the path of the
  9769.  file or directory. Wildcard characters are valid in the path only when the
  9770.  value of the usInfoLevel parameter is FIL_QUERYFULLNAME or FIL_NAMEISVALID.
  9771.  
  9772.  usInfoLevel  Specifies the level of information required. This parameter can
  9773.  be one of the following values:
  9774.  
  9775.  Value                             Meaning
  9776.  ────────────────────────────────────────────────────────────────────────────
  9777.  
  9778.  FIL_STANDARD                      Return a FILESTATUS structure.
  9779.  
  9780.  FIL_QUERYEASIZE                   Return a FILESTATUS structure followed
  9781.                                    by a 4-byte value that specifies the
  9782.                                    buffer size needed to retrieve the
  9783.                                    entire extended attribute.
  9784.  
  9785.  FIL_QUERYEASFROMLIST              Return extended-attribute information,
  9786.                                    using an EAOP structure for the pInfoBuf
  9787.                                    parameter. .
  9788.  
  9789.  FIL_QUERYFULLNAME                 Return the fully qualified path of the
  9790.                                    buffer pointed to by the pInfoBuf
  9791.                                    parameter. When this value is specified,
  9792.                                    the path pointed to by the pszPath
  9793.                                    parameter can contain wildcard
  9794.                                    characters.
  9795.  
  9796.  FIL_NAMEISVALID                   Verify the correctness (according to MS
  9797.                                    OS/2 syntax rules) of the path pointed
  9798.                                    to by the pszPath parameter. If the path
  9799.                                    is incorrect (for example, a filename is
  9800.                                    too long for the current file system),
  9801.                                    an error will be returned. The path can
  9802.                                    contain wildcard characters.
  9803.  
  9804.  
  9805.  
  9806.  pInfoBuf  Points to the buffer that contains a FILESTATUS or EAOP structure.
  9807.  The structure used is determined by the value specified for the usInfoLevel
  9808.  parameter.
  9809.  
  9810.  The FILESTATUS structure has the following form:
  9811.  
  9812.  typedef struct _FILESTATUS {
  9813.      FDATE  fdateCreation;
  9814.      FTIME  ftimeCreation;
  9815.      FDATE  fdateLastAccess;
  9816.      FTIME  ftimeLastAccess;
  9817.      FDATE  fdateLastWrite;
  9818.      FTIME  ftimeLastWrite;
  9819.      ULONG  cbFile;
  9820.      ULONG  cbFileAlloc;
  9821.      USHORT attrFile;
  9822.  } FILESTATUS;
  9823.  
  9824.  
  9825.  
  9826.  
  9827.  The EAOP structure has the following form:
  9828.  
  9829.  typedef struct _EAOP {
  9830.      PGEALIST fpGEAList;
  9831.      PFEALIST fpFEAList;
  9832.      ULONG    oError;
  9833.  } EAOP;
  9834.  
  9835.  
  9836.  
  9837.  
  9838.  For a full description, see Chapter 4, "Types, Macros, Structures."
  9839.  
  9840.  cbInfoBuf  Specifies the length (in bytes) of the buffer pointed to by the
  9841.  pInfoBuf parameter.
  9842.  
  9843.  ulReserved  Specifies a reserved value; must be zero.
  9844.  
  9845.  
  9846.  Return Value
  9847.  
  9848.  
  9849.  
  9850.  The return value is zero if the function is successful. Otherwise, it is an
  9851.  error value, which may be one of the following:
  9852.  
  9853.       ERROR_BUFFER_OVERFLOW
  9854.       ERROR_EA_LIST_INCONSISTENT
  9855.       ERROR_FILENAME_EXCED_RANGE
  9856.       ERROR_INVALID_EA_NAME
  9857.       ERROR_INVALID_LEVEL
  9858.       ERROR_PATH_NOT_FOUND
  9859.  
  9860.  
  9861.  
  9862.  
  9863.  
  9864.  Comments
  9865.  
  9866.  If the usInfoLevel parameter is FIL_QUERYEASFROMLIST, a subset of the
  9867.  extended-attribute information for the file is returned. Prior to the call
  9868.  to the DosQPathInfo function, the fpGEAList field of the EAOP structure
  9869.  should point to a list that defines the attribute names for which values
  9870.  will be returned, and the fpFEAList field should point to a buffer in which
  9871.  the relevant extended-attribute list will be returned.
  9872.  
  9873.  
  9874.  See Also
  9875.  
  9876.  DosQFileInfo, DosSetPathInfo
  9877.  
  9878.  
  9879.  █    DosRead
  9880.  ────────────────────────────────────────────────────────────────────────────
  9881.  
  9882.  USHORT DosRead  (hf, pvBuf, cbBuf, pcbBytesRead)
  9883.  
  9884.  HFILE  hf;                        /*file handle */
  9885.  
  9886.  PVOID  pvBuf;                     /*pointer to buffer receiving data */
  9887.  
  9888.  USHORT  cbBuf;                    /*number of bytes in buffer */
  9889.  
  9890.  PUSHORT  pcbBytesRead;            /*pointer to variable for number of
  9891.                                    bytes read */
  9892.  
  9893.  
  9894.  The DosRead function reads up to a specified number of bytes of data from a
  9895.  file into a buffer. The function may read fewer than the specified number of
  9896.  bytes if it reaches the end of the file.
  9897.  
  9898.  The DosRead function is a family API function.
  9899.  
  9900.  
  9901.  Parameters
  9902.  
  9903.  hf  Identifies the file to be read. This handle must have been created by
  9904.  using the DosOpen function.
  9905.  
  9906.  pvBuf  Points to the buffer that receives the data.
  9907.  
  9908.  cbBuf  Specifies the number of bytes to read from the file.
  9909.  
  9910.  pcbBytesRead  Points to the variable that receives the number of bytes read
  9911.  from the file. This parameter is zero if the file pointer is positioned at
  9912.  the end of the file prior to the call to the DosRead function.
  9913.  
  9914.  
  9915.  Return Value
  9916.  
  9917.  The return value is zero if the function is successful. Otherwise, it is an
  9918.  error value, which may be one of the following:
  9919.  
  9920.       ERROR_ACCESS_DENIED
  9921.       ERROR_BROKEN_PIPE
  9922.       ERROR_INVALID_HANDLE
  9923.       ERROR_LOCK_VIOLATION
  9924.       ERROR_NOT_DOS_DISK
  9925.  
  9926.  
  9927.  
  9928.  
  9929.  
  9930.  Comments
  9931.  
  9932.  The DosRead function does not return an error if the file pointer is at the
  9933.  end of the file when the read operation begins.
  9934.  
  9935.  When DosRead is used to read a byte pipe, the pipe must be in byte-read
  9936.  mode, an error is returned if the pipe is in message-read mode. All
  9937.  currently available data, up to the size requested, is returned.
  9938.  
  9939.  For a message pipe in message-read mode, a read operation that is larger
  9940.  than the next available message returns only that message, with pcbBytesRead
  9941.  set to indicate the size of the returned message. A read operation that is
  9942.  smaller than the next available message returns with the number of bytes
  9943.  requested and an ERROR_MORE_DATA error code. Subsequent DosRead calls will
  9944.  continue reading the message. The DosPeekNmPipe function can be used to
  9945.  determine how many bytes are left in the message.
  9946.  
  9947.  For a message pipe in byte-read mode, DosRead reads the pipe as if it were a
  9948.  byte stream, skipping over message headers. This is the same as reading a
  9949.  byte pipe in byte mode.
  9950.  
  9951.  When blocking mode is set, the read operation blocks until data is
  9952.  available. In this case, the read operation will never return with the
  9953.  pcbBytesRead parameter equal to zero except when it has read an end-of-file
  9954.  (EOF) character. Note that in message-read mode, messages are always read
  9955.  entirely, except in the case where the message is larger than the size
  9956.  specified for the read operation.
  9957.  
  9958.  When nonblocking mode is set, the read operation returns with the
  9959.  pcbBytesRead parameter equal to zero upon reading the EOF character. An
  9960.  error will be returned if no data is available.
  9961.  
  9962.  When resuming reading a message after an ERROR_MORE_DATA error occurs, the
  9963.  read operation always blocks until the next part of the message can be
  9964.  transferred. When nonblocking mode is set, the read operation can return
  9965.  with pcbBytesRead equal to zero if, upon attempting to read at the start of
  9966.  a message, it determines that no message is available.
  9967.  
  9968.  
  9969.  Example
  9970.  
  9971.  This example opens, reads, and displays the file abc:
  9972.  
  9973.  BYTE abBuf[512];
  9974.  HFILE hf;
  9975.  USHORT usAction, cbBytesRead, cbBytesWritten;
  9976.  DosOpen("abc", &hf, &usAction, 0L, FILE_NORMAL, FILE_OPEN,
  9977.      OPEN_ACCESS_READONLY | OPEN_SHARE_DENYNONE, 0L);
  9978.  do {
  9979.      DosRead(hf,           /* file handle                      */
  9980.          abBuf,            /* address of buffer                */
  9981.          sizeof(abBuf),    /* size of buffer                   */
  9982.          &cbBytesRead);    /* address for number of bytes read */
  9983.      DosWrite(1, abBuf, cbBytesRead, &cbBytesWritten);
  9984.  }
  9985.  while (cbBytesRead);
  9986.  
  9987.  
  9988.  
  9989.  
  9990.  
  9991.  See Also
  9992.  
  9993.  DosChgFilePtr, DosOpen, DosPeekNmPipe, DosReadAsync, DosWrite, KbdStringIn
  9994.  
  9995.  
  9996.  Corrections
  9997.  
  9998.  DosRead can be used to read from a named pipe. The comments have been
  9999.  updated to contain the relevant information about reading from a named pipe.
  10000.  
  10001.  
  10002.  
  10003.  █    DosReadAsync
  10004.  ────────────────────────────────────────────────────────────────────────────
  10005.  
  10006.  USHORT DosReadAsync  (hf, hsemRam, pusErrCode, pvBuf, cbBuf, pcbBytesRead)
  10007.  
  10008.  HFILE  hf;                        /*file handle */
  10009.  
  10010.  PULONG  hsemRam;                  /*pointer to RAM semaphore */
  10011.  
  10012.  PUSHORT  pusErrCode;              /*pointer to variable for error return
  10013.                                    code */
  10014.  
  10015.  PVOID  pvBuf;                     /*pointer to input buffer */
  10016.  
  10017.  USHORT  cbBuf;                    /*length of input buffer */
  10018.  
  10019.  PUSHORT  pcbBytesRead;            /*pointer to variable for number of
  10020.                                    bytes read */
  10021.  
  10022.  
  10023.  The DosReadAsync function reads one or more bytes of data from the file
  10024.  identified by the hf parameter. The function reads the data asynchronously;
  10025.  that is, the function returns immediately to the process that called it but
  10026.  continues to copy data to the specified buffer while the process continues.
  10027.  
  10028.  
  10029.  Parameters
  10030.  
  10031.  hf  Identifies the file to be read. This handle must have been previously
  10032.  opened by using the DosOpen function.
  10033.  
  10034.  hsemRam  Points to the RAM semaphore that indicates when the function has
  10035.  finished reading the data.
  10036.  
  10037.  pusErrCode  Points to the variable that receives any error code the function
  10038.  generates while reading data. The possible error codes are identical to
  10039.  those returned by the DosRead function.
  10040.  
  10041.  pvBuf  Points to the buffer that receives the data being read.
  10042.  
  10043.  cbBuf  Specifies the number of bytes to be read from the file identified by
  10044.  the hf parameter.
  10045.  
  10046.  pcbBytesRead  Points to the variable that receives the number of bytes read
  10047.  from the file.
  10048.  
  10049.  
  10050.  Return Value
  10051.  
  10052.  The return value is zero if the function is successful. Otherwise, it is an
  10053.  error value, which may be one of the following:
  10054.  
  10055.       ERROR_ACCESS_DENIED
  10056.       ERROR_BROKEN_PIPE
  10057.       ERROR_INVALID_HANDLE
  10058.       ERROR_LOCK_VIOLATION
  10059.       ERROR_NO_PROC_SLOTS
  10060.       ERROR_NOT_DOS_DISK
  10061.  
  10062.  
  10063.  
  10064.  
  10065.  
  10066.  Comments
  10067.  
  10068.  The DosReadAsync function reads up to the number of bytes specified in the
  10069.  cbBuf parameter, but it may read fewer if it reaches the end of the file. In
  10070.  any case, the function copies the number of bytes read to the variable
  10071.  pointed to by the pcbBytesRead parameter. The pcbBytesRead parameter is zero
  10072.  if all the bytes in the file have been read (that is, the end of file has
  10073.  been reached).
  10074.  
  10075.  If the process intends to use the RAM semaphore pointed to by the hsemRam
  10076.  parameter to determine when data is available, it must set the semaphore by
  10077.  using the DosSemSet function before calling DosReadAsync. When DosReadAsync
  10078.  has read the data, it clears the RAM semaphore.
  10079.  
  10080.  The DosReadAsync function carries out the asynchronous operation by creating
  10081.  a new thread that reads from the specified file. The function terminates the
  10082.  thread when the operation is complete or when an error occurs.
  10083.  
  10084.  When DosReadAsync is used to read a byte pipe, the pipe must be in byte-read
  10085.  mode; an error is returned if the pipe is in message-read mode. All
  10086.  currently available data, up to the size requested, is returned.
  10087.  
  10088.  For a message pipe in message-read mode, a read operation that is larger
  10089.  than the next available message returns only that message; pcbBytesRead is
  10090.  set to indicate the size of the message returned. A read operation that is
  10091.  smaller than the next available message returns with the number of bytes
  10092.  requested and an ERROR_MORE_DATA error code. Subsequent DosReadAsync calls
  10093.  will continue reading the message. DosPeekNmPipe may be used to determine
  10094.  how many bytes are left in the message.
  10095.  
  10096.  For a message pipe in byte-read mode, DosReadAsync reads the pipe as if it
  10097.  were a byte stream, skipping over message headers. This is the same as
  10098.  reading a byte pipe in byte mode.
  10099.  
  10100.  When blocking mode is set, a read operation blocks until data is available.
  10101.  In this case, the read operation will not return with the pcbBytesRead
  10102.  parameter equal to zero except when it has read an end-of-file (EOF)
  10103.  character. Note that in message-read mode, messages are always read
  10104.  entirely, except in the case where the message is larger than the size
  10105.  specified for the read operation.
  10106.  
  10107.  When nonblocking mode is set, a read operation returns with pcbBytesRead
  10108.  equal to zero upon reading the EOF character. An error will be returned if
  10109.  there is no data available.
  10110.  
  10111.  When resuming reading a message after an ERROR_MORE_DATA message, the read
  10112.  operation always blocks until the next part of the message can be
  10113.  transferred. When nonblocking mode is set, the read operation can return
  10114.  with pcbByteRead equal to zero if, upon attempting to read at the start of a
  10115.  message, it determines that no message is available.
  10116.  
  10117.  
  10118.  Example
  10119.  
  10120.  This example opens the file abc, sets a RAM semaphore, and calls the
  10121.  DosReadAsync function to read part of the file. While the file is being
  10122.  read, program execution continues until the call to the DosSemWait function,
  10123.  which does not return until the DosReadAsync thread completes its work.
  10124.  
  10125.  BYTE abBuf[512];
  10126.  ULONG hReadSemaphore = 0;
  10127.  HFILE hf;
  10128.  USHORT usAction, cbBytesRead;
  10129.  USHORT usReadReturn;
  10130.  DosOpen("abc", &hf, &usAction, 0L, FILE_NORMAL, FILE_OPEN,
  10131.      OPEN_ACCESS_READONLY | OPEN_SHARE_DENYNONE, 0L);
  10132.  DosSemSet(&hReadSemaphore);     /* sets RAM semaphore           */
  10133.  DosReadAsync(hf,                /* handle to file               */
  10134.      &hReadSemaphore,            /* address of semaphore         */
  10135.      &usReadReturn,              /* address to store return code */
  10136.      abBuf,                      /* address of buffer            */
  10137.      sizeof(abBuf),              /* size of buffer               */
  10138.      &cbBytesRead);              /* number of bytes read         */
  10139.      .
  10140.      . /* Other processing occurs here. */
  10141.      .
  10142.  DosSemWait(&hReadSemaphore, -1L);
  10143.  
  10144.  
  10145.  
  10146.  
  10147.  
  10148.  See Also
  10149.  
  10150.  DosOpen, DosPeekNmPipe, DosRead, DosSemSet, DosSemWait, DosWriteAsync
  10151.  
  10152.  
  10153.  Changes
  10154.  
  10155.  Information about using this function with pipes has been added.
  10156.  
  10157.  
  10158.  █    DosReadQueue
  10159.  ────────────────────────────────────────────────────────────────────────────
  10160.  
  10161.  USHORT DosReadQueue  (hqueue, pqresc, pcbElement, ppv, usElement, fWait,
  10162.  pbElemPrty, hsem)
  10163.  
  10164.  HQUEUE  hqueue;                   /*handle of queue to read */
  10165.  
  10166.  PQUEUERESULT  pqresc;             /*pointer to structure for PID and
  10167.                                    request code */
  10168.  
  10169.  PUSHORT  pcbElement;              /*pointer to variable for length of
  10170.                                    element */
  10171.  
  10172.  PVOID FAR \*  ppv;                /*pointer to buffer for element */
  10173.  
  10174.  USHORT  usElement;                /*element number to read */
  10175.  
  10176.  UCHAR  fWait;                     /*wait/no wait indicator */
  10177.  
  10178.  PBYTE  pbElemPrty;                /*pointer to variable for priority of
  10179.                                    element */
  10180.  
  10181.  HSEM  hsem;                       /*semaphore handle */
  10182.  
  10183.  
  10184.  The DosReadQueue function retrieves an element and then removes it from a
  10185.  queue. It copies the address of the element to the supplied pointer and
  10186.  fills a structure with information about the element.
  10187.  
  10188.  
  10189.  Parameters
  10190.  
  10191.  hqueue  Identifies the queue to read. This handle must have been created or
  10192.  opened by using the DosCreateQueue or DosOpenQueue function.
  10193.  
  10194.  pqresc  Points to the QUEUERESULT structure that receives information about
  10195.  the request. The QUEUERESULT structure has the following form:
  10196.  
  10197.  typedef struct _QUEUERESULT {
  10198.      PID pidProcess;
  10199.      USHORT usEventCode;
  10200.  } QUEUERESULT;
  10201.  
  10202.  
  10203.  
  10204.  
  10205.  For a full description, see Chapter 4, "Types, Macros, Structures."
  10206.  
  10207.  pcbElement  Points to the variable that receives the length (in bytes) of
  10208.  the element.
  10209.  
  10210.  ppv  Points to the pointer that receives the address of the element in the
  10211.  queue.
  10212.  
  10213.  usElement  Specifies where to look in the queue for the element. If this
  10214.  parameter is 0x0000, the function looks at the beginning of the queue.
  10215.  Otherwise, the function assumes the value is an element identifier retrieved
  10216.  by using the DosPeekQueue function and looks for the specified element.
  10217.  
  10218.  fWait  Specifies whether to wait for an element to be placed in the queue,
  10219.  if the queue is empty. If this parameter is DCWW_WAIT, the function waits
  10220.  until an element is available. If this parameter is DCWW_NOWAIT, the
  10221.  function returns immediately with a code that indicates there are no entries
  10222.  in the queue. Note that in order to use these constants, you must define the
  10223.  INCL_DOSPROCESS include constant before specifying the os2.h header file.
  10224.  
  10225.  pbElemPrty  Points to the variable that receives the priority value
  10226.  specified when the element was added to the queue. This is a value in the
  10227.  range 0 through 15; 15 indicates the highest priority.
  10228.  
  10229.  hsem  Identifies a semaphore. This value can be the handle of a system
  10230.  semaphore that has been created or opened by using the DosCreateSem or the
  10231.  DosOpenSem function, or it can be the address of a RAM semaphore. This
  10232.  semaphore would typically be used in a call to the DosMuxSemWait function to
  10233.  wait until the queue has an element. If the fWait parameter is DCWW_WAIT,
  10234.  hsem is ignored.
  10235.  
  10236.  
  10237.  Return Value
  10238.  
  10239.  The return value is zero if the function is successful. Otherwise, it is an
  10240.  error value, which may be one of the following:
  10241.  
  10242.        ERROR_QUE_ELEMENT_NOT_EXIST
  10243.        ERROR_QUE_EMPTY
  10244.        ERROR_QUE_INVALID_HANDLE
  10245.        ERROR_QUE_INVALID_WAIT
  10246.        ERROR_QUE_PROC_NOT_OWNED
  10247.  
  10248.  
  10249.  
  10250.  
  10251.  
  10252.  Comments
  10253.  
  10254.  If the queue is empty, the DosReadQueue function either returns immediately
  10255.  or waits for an element to be written to the queue, depending on the value
  10256.  of the fWait parameter.
  10257.  
  10258.  Only the process that created the queue can call the DosReadQueue function.
  10259.  
  10260.  
  10261.  Example
  10262.  
  10263.  This example reads the queue and waits until an element is received. After
  10264.  the element is read and the data processed, the process frees the shared
  10265.  memory that was passed to it. This assumes the process writing to the queue
  10266.  created a shared-memory segment. For more information, see the DosWriteQueue
  10267.  function.
  10268.  
  10269.  QUEUERESULT qresc;
  10270.  USHORT cbElement;
  10271.  PVOID pv;
  10272.  BYTE bElemPrty;
  10273.  
  10274.  DosReadQueue(hqueue,        /* queue handle                        */
  10275.      &qresc,                 /* address of result structure         */
  10276.      &cbElement,             /* receives element number             */
  10277.      &pv,                    /* receives data address               */
  10278.      0,                      /* element number to read              */
  10279.      DCWW_WAIT,              /* waits until something is written    */
  10280.      &bElemPrty,             /* receives priority level             */
  10281.      (HSEM) NULL);           /* semaphore not needed, since waiting */
  10282.      .
  10283.      .   /* Process the data. */
  10284.      .
  10285.  DosFreeSeg(SELECTOROF(pv));                 /* frees shared memory */
  10286.  
  10287.  
  10288.  
  10289.  
  10290.  
  10291.  See Also
  10292.  
  10293.  DosCreateQueue, DosMuxSemWait, DosOpenQueue, DosOpenSem, DosPeekQueue,
  10294.  DosWriteQueue
  10295.  
  10296.  
  10297.  Corrections
  10298.  
  10299.  The description incorrectly stated that the element was copied to the
  10300.  supplied buffer. It is the address of the element that is copied to the
  10301.  supplied pointer. No data is actually copied; only the pointer to the data
  10302.  is copied.
  10303.  
  10304.  In order to use the DCWW_WAIT and DCWW_NOWAIT constants, you must define the
  10305.  INCL_DOSPROCESS include constant before specifying the os2.h header file.
  10306.  
  10307.  
  10308.  █    DosReallocHuge
  10309.  ────────────────────────────────────────────────────────────────────────────
  10310.  
  10311.  USHORT DosReallocHuge  (usNumSeg, usPartialSeg, sel)
  10312.  
  10313.  USHORT  usNumSeg;                 /*number of 65,536-byte segments */
  10314.  
  10315.  USHORT  usPartialSeg;             /*number of bytes in last segment */
  10316.  
  10317.  SEL  sel;                         /*segment selector */
  10318.  
  10319.  
  10320.  The DosReallocHuge function reallocates a huge-memory block. This function
  10321.  changes the size of the huge memory to the specified number of 65,536-byte
  10322.  segments plus an additional segment of a specified size.
  10323.  
  10324.  The DosReallocHuge function is a family API function.
  10325.  
  10326.  
  10327.  Parameters
  10328.  
  10329.  usNumSeg  Specifies the number of 65,536-byte segments to allocate.
  10330.  
  10331.  usPartialSeg  Specifies the number of bytes in the last segment. This number
  10332.  can be any value in the range 0 through 65,535. If this number is zero, no
  10333.  additional segment is allocated.
  10334.  
  10335.  sel  Specifies the selector for the huge-memory block to be reallocated. The
  10336.  selector must have been created by using the DosAllocHuge function.
  10337.  
  10338.  
  10339.  Return Value
  10340.  
  10341.  The return value is zero if the function is successful. Otherwise, it is an
  10342.  error value, which may be one of the following:
  10343.  
  10344.       ERROR_INVALID_PARAMETER
  10345.       ERROR_NOT_ENOUGH_MEMORY
  10346.  
  10347.  
  10348.  
  10349.  
  10350.  
  10351.  Comments
  10352.  
  10353.  The DosReallocHuge function does not change the shareable and discardable
  10354.  attributes of the segments in the huge-memory block. If it was originally a
  10355.  shareable or discardable block, it remains a shareable or discardable block.
  10356.  However, if DosReallocHuge reallocates a discardable block, it also locks
  10357.  the segments. The DosUnlockSeg function must be used to unlock the segments
  10358.  and permit discarding.
  10359.  
  10360.  The huge-memory block cannot be reallocated for a size larger than the
  10361.  maximum specified by the usMaxNumSeg parameter in the original call to the
  10362.  DosAllocHuge function.
  10363.  
  10364.  Each segment in the huge-memory block has a unique selector. The selectors
  10365.  are consecutive. The sel parameter specifies the value of the first
  10366.  selector; the remaining selectors can be computed by adding the selector
  10367.  offset to the first selector one or more times─that is, once for the second
  10368.  selector, twice for the third, and so on. The selector offset is a multiple
  10369.  of 2, as specified by the shift count retrieved by using the DosGetHugeShift
  10370.  function. For example, if the shift count is 2, the selector offset is 4 (1
  10371.  < 2). If the selector offset is 4 and the first selector is 6, the second
  10372.  selector is 10, the third is 14, and so on.
  10373.  
  10374.  Typically, DosReallocHuge can increase, not decrease, the size of shared
  10375.  huge segments. If the shared segment is allocated by the DosAllocHuge
  10376.  function, the segment can be decreased in size by setting the fsAttr
  10377.  parameter to SEG_SIZEABLE.
  10378.  
  10379.  DosReallocHuge can be issued from ring 2, but only ring-3 segments are
  10380.  affected by this function.
  10381.  
  10382.  
  10383.  Restrictions
  10384.  
  10385.  In real mode, the following restriction applies to the DosReallocHuge
  10386.  function:
  10387.  
  10388.    ■   The usPartialSeg parameter is rounded up to the next paragraph
  10389.        (16-byte) value.
  10390.  
  10391.  
  10392.  
  10393.  
  10394.  See Also
  10395.  
  10396.  DosAllocHuge, DosFreeSeg, DosGetHugeShift, DosLockSeg, DosReallocSeg,
  10397.  DosUnlockSeg
  10398.  
  10399.  
  10400.  Changes
  10401.  
  10402.  Typically, DosReallocHuge can increase, not decrease, the size of shared
  10403.  huge segments. If the shared segment is allocated by the DosAllocHuge
  10404.  function, the segment can be decreased in size by setting the fsAttr
  10405.  parameter to SEG_SIZEABLE.
  10406.  
  10407.  DosReallocHuge can be issued from ring 2, but only ring-3 segments are
  10408.  affected by this function.
  10409.  
  10410.  
  10411.  █    DosReallocSeg
  10412.  ────────────────────────────────────────────────────────────────────────────
  10413.  
  10414.  USHORT DosReallocSeg  (usNewSize, sel)
  10415.  
  10416.  USHORT  usNewSize;                /*new segment size */
  10417.  
  10418.  SEL  sel;                         /*segment selector */
  10419.  
  10420.  
  10421.  The DosReallocSeg function reallocates a segment. The function changes the
  10422.  size of the segment to the number of bytes specified by the usNewSize
  10423.  parameter.
  10424.  
  10425.  The DosReallocSeg function is a family API function.
  10426.  
  10427.  
  10428.  Parameters
  10429.  
  10430.  usNewSize  Specifies the new size (in bytes). The size can be any number
  10431.  from 0 through 65,535. If it is 0, the function allocates 65,536 bytes.
  10432.  
  10433.  sel  Specifies the selector of the segment to be reallocated. The selector
  10434.  must have been created previously by using DosAllocSeg or DosAllocShrSeg.
  10435.  
  10436.  
  10437.  Return Value
  10438.  
  10439.  The return value is zero if the function is successful. Otherwise, it is an
  10440.  error value, which may be one of the following:
  10441.  
  10442.       ERROR_ACCESS_DENIED
  10443.       ERROR_NOT_ENOUGH_MEMORY
  10444.  
  10445.  
  10446.  
  10447.  
  10448.  
  10449.  Comments
  10450.  
  10451.  The DosReallocSeg function does not change the shareable and discardable
  10452.  attributes of the segment. If it was originally a shareable or discardable
  10453.  segment, it remains a shareable or discardable segment. If DosReallocSeg
  10454.  reallocates a discardable segment, however, it also locks the segment. You
  10455.  must use the DosUnlockSeg function to unlock the segment and permit
  10456.  discarding.
  10457.  
  10458.  If the DosReallocSeg function is used to reallocate a shared segment to a
  10459.  size smaller than its original size, the segment must have been created
  10460.  using the DosAllocSeg function with the SEG_SIZEABLE attribute set. This
  10461.  request can be issued from ring 2 or ring 3; the segment to be reallocated
  10462.  can be a ring-2 or a ring-3 segment.
  10463.  
  10464.  The DosReallocSeg function cannot be used to reallocate a segment created by
  10465.  the DosCreateCSAlias function.
  10466.  
  10467.  
  10468.  Restrictions
  10469.  
  10470.  In real mode, the following restriction applies to the DosReallocSeg
  10471.  function:
  10472.  
  10473.    ■   The usNewSize parameter is rounded up to the next paragraph (16-byte)
  10474.        value.
  10475.  
  10476.  
  10477.  
  10478.  
  10479.  Example
  10480.  
  10481.  This example allocates a segment with 16,000 bytes, and then calls
  10482.  DosReallocSeg to increase the size to 32,000 bytes.
  10483.  
  10484.  SEL sel;
  10485.  
  10486.  DosAllocSeg(16000, &sel, SEG_NONSHARED);   /* allocates memory   */
  10487.      .
  10488.      .
  10489.      .
  10490.  DosReallocSeg(32000, sel);                 /* reallocates memory */
  10491.  
  10492.  
  10493.  
  10494.  
  10495.  
  10496.  See Also
  10497.  
  10498.  DosAllocSeg, DosFreeSeg, DosLockSeg, DosReallocHuge, DosUnlockSeg
  10499.  
  10500.  
  10501.  Changes
  10502.  
  10503.  If DosReallocSeg is used to reallocate a shared segment to a size smaller
  10504.  than its original size, the segment must have been created using the
  10505.  DosAllocSeg function with the SEG_SIZEABLE attribute set. This request can
  10506.  be issued from ring 2 or ring 3; the segment to be reallocated can be either
  10507.  a ring-2 or a ring-3 segment.
  10508.  
  10509.  
  10510.  █    DosSearchPath
  10511.  ────────────────────────────────────────────────────────────────────────────
  10512.  
  10513.  USHORT DosSearchPath  (fsSearch, pszPath, pszFileName, pbBuf, cbBuf)
  10514.  
  10515.  USHORT  fsSearch;                 /*search flags */
  10516.  
  10517.  PSZ  pszPath;                     /*pointer to search path or environment
  10518.                                    variable */
  10519.  
  10520.  PSZ  pszFileName;                 /*pointer to filename */
  10521.  
  10522.  PBYTE  pbBuf;                     /*pointer to result buffer */
  10523.  
  10524.  USHORT  cbBuf;                    /*length of result buffer */
  10525.  
  10526.  
  10527.  The DosSearchPath function searches the specified search path for the given
  10528.  filename. The search path is a null-terminated string that consists of a
  10529.  sequence of directory paths separated by semicolons (;). The function
  10530.  searches for the filename by looking in each directory (one directory at a
  10531.  time) in the order given.
  10532.  
  10533.  
  10534.  Parameters
  10535.  
  10536.  fsSearch  Specifies how to interpret the pszPath parameter and whether to
  10537.  search the current directory. This parameter can be a combination of the
  10538.  following values:
  10539.  
  10540.  Value                             Meaning
  10541.  ────────────────────────────────────────────────────────────────────────────
  10542.  
  10543.  DSP_ENVIRONMENT                   The pszPath parameter points to the name
  10544.                                    of an environment variable. The function
  10545.                                    retrieves the value of the environment
  10546.                                    variable from the environment segment of
  10547.                                    the process and uses it as the search
  10548.                                    path. If this value is not specified,
  10549.                                    pszPath points to a string that
  10550.                                    specifies the search path. This value
  10551.                                    cannot be used with the DSP_PATH value.
  10552.  
  10553.  DSP_IGNORE_NET_ERR                If this value is set, the search ignores
  10554.                                    any network errors encountered during
  10555.                                    during processing and continues to
  10556.                                    search the remainder of the path. If
  10557.                                    this value is not specified, a network
  10558.                                    error (for example, when a server is
  10559.                                    unavailable) causes the search to halt.
  10560.  
  10561.  DSP_CUR_DIRECTORY                 The function searches the current
  10562.                                    directory before it searches the first
  10563.                                    directory in the search path. If this
  10564.                                    value is not specified, the function
  10565.                                    searches the current directory only if
  10566.                                    it is explicitly given in the search
  10567.                                    path.
  10568.  
  10569.  DSP_PATH                          The pszPath parameter points to a string
  10570.                                    that specifies the search path. This
  10571.                                    value cannot be used with the
  10572.                                    DSP_ENVIRONMENT value.
  10573.  
  10574.  
  10575.  
  10576.  pszPath  Points to the null-terminated string that specifies the search
  10577.  path. If DSP_ENVIRONMENT is specified for the fsSearch parameter, the
  10578.  pszPath parameter points to an environment variable. Otherwise, the pszPath
  10579.  param- eter points to one or more paths to search. The paths are separated
  10580.  by semicolons (;).
  10581.  
  10582.  pszFileName  Points to a null-terminated string that specifies the filename
  10583.  to search for. The string must be a valid MS OS/2 filename and can contain
  10584.  wildcard characters.
  10585.  
  10586.  pbBuf  Points to the buffer that receives the full path name of the file if
  10587.  the filename is found.
  10588.  
  10589.  cbBuf  Specifies the length (in bytes) of the buffer pointed to by the pbBuf
  10590.  parameter.
  10591.  
  10592.  
  10593.  Return Value
  10594.  
  10595.  The return value is zero if the function is successful. Otherwise, it is an
  10596.  error value.
  10597.  
  10598.  
  10599.  Comments
  10600.  
  10601.  If DosSearchPath finds a matching filename in any of the directories
  10602.  specified by the search path, the function copies the full, null-terminated
  10603.  path name to the buffer pointed to by the pbBuf parameter. If the filename
  10604.  pointed to by the pszFileName parameter contains wildcard characters, the
  10605.  resulting path name will also contain wildcard characters; the DosFindFirst
  10606.  function can be used to retrieve the actual filename(s).
  10607.  
  10608.  The DosSearchPath function does not check for the validity of filenames. If
  10609.  the filename is not valid, the function returns an error, indicating that
  10610.  the file was not found.
  10611.  
  10612.  
  10613.  Example
  10614.  
  10615.  This example uses the search path specified by the DPATH environment
  10616.  variable to search for the abc.txt filename:
  10617.  
  10618.  CHAR szFoundFile[CCHMAXPATH];
  10619.  DosSearchPath(DSP_ENVIRONMENT,   /* uses environment variable   */
  10620.      "DPATH",                     /* uses DPATH search path      */
  10621.      "abc.txt",                   /* filename                    */
  10622.      szFoundFile,                 /* receives resulting filename */
  10623.      sizeof(szFoundFile));        /* length of result buffer     */
  10624.  
  10625.  
  10626.  
  10627.  
  10628.  The following example is identical to the first example if the DPATH
  10629.  variable is defined as shown:
  10630.  
  10631.  DPATH=c:\sysdir;c:\init
  10632.  
  10633.  
  10634.  
  10635.  DosSearchPath(DSP_PATH,          /* uses search path            */
  10636.      "c:\\sysdir;c:\\init",       /* search path                 */
  10637.      "abc.txt",                   /* filename                    */
  10638.      szFoundFile,                 /* receives resulting filename */
  10639.      sizeof(szFoundFile));        /* length of result buffer     */
  10640.  
  10641.  
  10642.  
  10643.  
  10644.  
  10645.  See Also
  10646.  
  10647.  DosFindFirst, DosScanEnv
  10648.  
  10649.  
  10650.  Changes
  10651.  
  10652.  The constants SEARCH_PATH, SEARCH_CUR_DIRECTORY, and SEARCH_ENVIRONMENT have
  10653.  been changed to DSP_PATH, DSP_CUR_DIRECTORY, and DSP_ENVIRONMENT,
  10654.  respectively. A new constant, DSP_IGNORE_NET_ERR, has been added to allow
  10655.  searches to continue when a network drive specified in the path might not be
  10656.  available at the time of the search.
  10657.  
  10658.  
  10659.  █    DosSemClear
  10660.  ────────────────────────────────────────────────────────────────────────────
  10661.  
  10662.  USHORT DosSemClear  (hsem)
  10663.  
  10664.  HSEM  hsem;                       /*semaphore handle */
  10665.  
  10666.  
  10667.  The DosSemClear function clears a system or RAM semaphore that has been set
  10668.  by using the DosSemRequest, DosSemSet, or DosSemSetWait function.
  10669.  
  10670.  
  10671.  Parameters
  10672.  
  10673.  hsem  Identifies the semaphore to clear. This value can be the handle of a
  10674.  system semaphore that has been previously created or opened by using the
  10675.  DosCreateSem or DosOpenSem function, or it can be the address of a RAM
  10676.  semaphore.
  10677.  
  10678.  
  10679.  Return Value
  10680.  
  10681.  The return value is zero if the function is successful. Otherwise, it is an
  10682.  error value, which may be the following:
  10683.  
  10684.       ERROR_EXCL_SEM_ALREADY_OWNED
  10685.  
  10686.  
  10687.  
  10688.  
  10689.  
  10690.  Comments
  10691.  
  10692.  The DosSemClear function cannot clear a system semaphore that is owned by
  10693.  another process unless the semaphore is nonexclusive.
  10694.  
  10695.  
  10696.  Example
  10697.  
  10698.  This example uses the DosSemClear function to clear a RAM semaphore and a
  10699.  system semaphore:
  10700.  
  10701.  ULONG hsem = 0;
  10702.  HSYSSEM hsys;
  10703.  DosSemClear(&hsem);   /* clears RAM semaphore    */
  10704.  DosSemClear(hsys);    /* clears system semaphore */
  10705.  
  10706.  
  10707.  
  10708.  
  10709.  
  10710.  See Also
  10711.  
  10712.  DosCreateSem, DosMuxSemWait, DosOpenSem, DosSemRequest, DosSemSet,
  10713.  DosSemSetWait, DosSemWait
  10714.  
  10715.  
  10716.  Corrections
  10717.  
  10718.  The example incorrectly used the address of the system semaphore rather than
  10719.  the handle of the system semaphore. System semaphores require the handle of
  10720.  the semaphore; RAM semaphores require the address of the semaphore.
  10721.  
  10722.  
  10723.  █    DosSemRequest
  10724.  ────────────────────────────────────────────────────────────────────────────
  10725.  
  10726.  USHORT DosSemRequest  (hsem, lTimeOut)
  10727.  
  10728.  HSEM  hsem;                       /*semaphore handle */
  10729.  
  10730.  LONG  lTimeOut;                   /*time out */
  10731.  
  10732.  
  10733.  The DosSemRequest function obtains and sets a semaphore. If no previous
  10734.  thread has set the semaphore, DosSemRequest sets the semaphore and returns
  10735.  immediately. If the semaphore has already been set by another thread, the
  10736.  function waits until a thread clears the semaphore (by using the DosSemClear
  10737.  function) or until a time-out occurs. The DosSemRequest function is also
  10738.  used to obtain ownership of a system semaphore created with the CSEM_PRIVATE
  10739.  flag set (see DosCreateSem).
  10740.  
  10741.  
  10742.  Parameters
  10743.  
  10744.  hsem  Identifies the semaphore to set. This value can be the handle of a
  10745.  system semaphore that has been previously created or opened by using the
  10746.  DosCreateSem or DosOpenSem function, or it can be the address of a RAM
  10747.  semaphore.
  10748.  
  10749.  lTimeOut  Specifies how long to wait for the semaphore to clear. If the
  10750.  value is greater then zero, this parameter specifies the number of
  10751.  milliseconds to wait before returning. If the value is SEM_IMMEDIATE_RETURN,
  10752.  the function returns immediately. If the value is SEM_INDEFINITE_WAIT, the
  10753.  function waits indefinitely.
  10754.  
  10755.  
  10756.  Return Value
  10757.  
  10758.  The return value is zero if the function is successful. Otherwise, it is an
  10759.  error value, which may be one of the following:
  10760.  
  10761.       ERROR_INTERRUPT
  10762.       ERROR_SEM_OWNER_DIED
  10763.       ERROR_SEM_TIMEOUT
  10764.       ERROR_TOO_MANY_SEM_REQUESTS
  10765.  
  10766.  
  10767.  
  10768.  
  10769.  
  10770.  Comments
  10771.  
  10772.  If DosSemRequest is used to obtain exclusive ownership of a semaphore
  10773.  created by another process, it will wait (if lTimeOut is non-zero) until the
  10774.  semaphore is clear, or until the process that currently owns the semaphore
  10775.  closes the semaphore or terminates. If the process owning the semaphore
  10776.  terminates, DosSemRequest will return with an error value of
  10777.  ERROR_SEM_OWNER_DIED; however ownership will be transferred and the
  10778.  semaphore will be set and can be used by the calling process.
  10779.  
  10780.  The effects of DosSemRequest are cumulative. If multiple calls to the
  10781.  DosSemRequest function set the semaphore, the same number of calls to the
  10782.  DosSemClear function are required to clear the semaphore.
  10783.  
  10784.  If more than one thread has requested to set the semaphore, a thread may
  10785.  have to wait through several changes of the semaphore before it continues
  10786.  (depending on which thread clears the semaphore and when the system
  10787.  scheduler passes control to the thread). As long as the semaphore is set
  10788.  (even if it has been cleared and reset since the thread originally called
  10789.  the function), the thread must wait.
  10790.  
  10791.  The DosSemRequest function can set system or RAM semaphores. A system
  10792.  semaphore is initially clear when it is created. A RAM semaphore is clear if
  10793.  its value is zero. Programs that use RAM semaphores should assign the
  10794.  initial value of zero.
  10795.  
  10796.  
  10797.  Example
  10798.  
  10799.  This example uses the DosSemRequest function to create a RAM semaphore. It
  10800.  also shows how to set and clear the semaphore.
  10801.  
  10802.  ULONG hsem = 0;
  10803.  DosSemRequest(&hsem,           /* address of handle  */
  10804.      SEM_INDEFINITE_WAIT);      /* waits indefinitely */
  10805.      .
  10806.      .
  10807.      .
  10808.  DosSemClear(&hsem);            /* clears semaphore   */
  10809.  
  10810.  
  10811.  
  10812.  
  10813.  
  10814.  See Also
  10815.  
  10816.  DosCreateSem, DosExitList, DosMuxSemWait, DosOpenSem, DosSemClear,
  10817.  DosSemSet, DosSemSetWait, DosSemWait
  10818.  
  10819.  
  10820.  Corrections
  10821.  
  10822.  DosSemRequest is used not only to set a semaphore once it becomes clear, but
  10823.  also to obtain exclusive ownership of a system semaphore created with the
  10824.  CSEM_PRIVATE flag.
  10825.  
  10826.  
  10827.  █    DosSetFileInfo
  10828.  ────────────────────────────────────────────────────────────────────────────
  10829.  
  10830.  USHORT DosSetFileInfo  (hf, usInfoLevel, pInfoBuf, cbInfoBuf)
  10831.  
  10832.  HFILE  hf;                        /*handle of file about which data is
  10833.                                    sought */
  10834.  
  10835.  USHORT  usInfoLevel;              /*level of file data required */
  10836.  
  10837.  PBYTE  pInfoBuf;                  /*pointer to file-data buffer */
  10838.  
  10839.  USHORT  cbInfoBuf;                /*length of file-data buffer */
  10840.  
  10841.  
  10842.  The DosSetFileInfo function sets information about a specific file. The file
  10843.  information consists of the date and time the file was created, the date and
  10844.  time it was last accessed, the date and time it was last written to, the
  10845.  size of the file, and its attributes. It can also be used to set extended
  10846.  attributes for a file.
  10847.  
  10848.  The DosSetFileInfo function is a family API function.
  10849.  
  10850.  
  10851.  Parameters
  10852.  
  10853.  hf  Identifies the file about which information is to be set. This handle
  10854.  must have been created by using the DosOpen function.
  10855.  
  10856.  usInfoLevel  Specifies the level of file information. This may be one of the
  10857.  following values:
  10858.  
  10859.  Value                             Meaning
  10860.  ────────────────────────────────────────────────────────────────────────────
  10861.  
  10862.  FIL_STANDARD                      This uses a FILESTATUS structure. Any
  10863.                                    date and time fields in this structure
  10864.                                    that the file system does not support
  10865.                                    should be set to zero.
  10866.  
  10867.  FIL_EAOP                          This uses an EAOP structure, which
  10868.                                    contains the file's extended-attribute
  10869.                                    information.
  10870.  
  10871.  
  10872.  
  10873.  pInfoBuf  Points to the structure that contains the file information. This
  10874.  structure will be FILESTATUS or EAOP, depending on the usInfoLevel
  10875.  parameter.
  10876.  
  10877.  The FILESTATUS structure has the following form:
  10878.  
  10879.  typedef struct _FILESTATUS {
  10880.      FDATE  fdateCreation;
  10881.      FTIME  ftimeCreation;
  10882.      FDATE  fdateLastAccess;
  10883.      FTIME  ftimeLastAccess;
  10884.      FDATE  fdateLastWrite;
  10885.      FTIME  ftimeLastWrite;
  10886.      ULONG  cbFile;
  10887.      ULONG  cbFileAlloc;
  10888.      USHORT attrFile;
  10889.  } FILESTATUS;
  10890.  
  10891.  
  10892.  
  10893.  
  10894.  The EAOP structure has the following form:
  10895.  
  10896.  typedef struct _EAOP {
  10897.      PGEALIST fpGEAList;
  10898.      PFEALIST fpFEAList;
  10899.      ULONG  oError;
  10900.  } EAOP;
  10901.  
  10902.  
  10903.  
  10904.  
  10905.  For a full description, see Chapter 4, "Types, Macros, Structures."
  10906.  
  10907.  cbInfoBuf  Specifies the length (in bytes) of the buffer that contains the
  10908.  file information.
  10909.  
  10910.  
  10911.  Return Value
  10912.  
  10913.  The return value is zero if the function is successful. Otherwise, it is an
  10914.  error value, which may be one of the error values on the following page:
  10915.  
  10916.       ERROR_BUFFER_OVERFLOW
  10917.       ERROR_DIRECT_ACCESS_HANDLE
  10918.       ERROR_EA_LIST_INCONSISTENT
  10919.       ERROR_INVALID_EA_NAME
  10920.       ERROR_INVALID_HANDLE
  10921.       ERROR_INVALID_LEVEL
  10922.  
  10923.  
  10924.  
  10925.  
  10926.  
  10927.  Comments
  10928.  
  10929.  DosSetFileInfo works only for files opened in a mode that allows write
  10930.  access.
  10931.  
  10932.  Prior to the function being called, the fpFEAlist field in the EAOP
  10933.  structure should be initialized so that it points to the FEALIST structure
  10934.  that contains the relevant FEA structure. The cbList field in the FEALIST
  10935.  structure is valid, giving the size of the FEA structure.
  10936.  
  10937.  A zero value in both the date and time components of a field causes that
  10938.  field to be unchanged. For example, if both the fdateLastWrite and
  10939.  ftimeLastWrite fields are zero in the FILESTATUS structure, both attributes
  10940.  of the file remain unchanged. If either of these fields are nonzero, both
  10941.  attributes of the file are set to the new values. If extended attributes are
  10942.  modified, the file's last modification date and time are changed.
  10943.  
  10944.  
  10945.  See Also
  10946.  
  10947.  DosBufReset, DosClose, DosNewSize, DosOpen, DosSetFileMode, DosQFileInfo
  10948.  
  10949.  
  10950.  Changes
  10951.  
  10952.  The constant FIL_EAOP has been added.
  10953.  
  10954.  
  10955.  █    DosSetMaxFH
  10956.  ────────────────────────────────────────────────────────────────────────────
  10957.  
  10958.  USHORT DosSetMaxFH  (usHandles)
  10959.  
  10960.  USHORT  usHandles;                /*number of file handles */
  10961.  
  10962.  
  10963.  The DosSetMaxFH function sets the maximum number of available file handles
  10964.  for the current process and any of its child processes. The number of
  10965.  available handles limits the number of files that can be opened at the same
  10966.  time.
  10967.  
  10968.  
  10969.  Parameters
  10970.  
  10971.  usHandles  Specifies the maximum number of file handles provided to the
  10972.  calling process. The maximum value for this parameter is 32,768; the minimum
  10973.  is 20. This number must not be smaller than the current number of file
  10974.  handles allocated.
  10975.  
  10976.  
  10977.  Return Value
  10978.  
  10979.  The return value is zero if the function is successful. Otherwise, it is an
  10980.  error value, which may be one of the following:
  10981.  
  10982.       ERROR_INVALID_PARAMETER
  10983.       ERROR_NOT_ENOUGH_MEMORY
  10984.  
  10985.  
  10986.  
  10987.  
  10988.  
  10989.  Comments
  10990.  
  10991.  This function preserves all currently open file handles.
  10992.  
  10993.  There are three handles in use when a process is started─for standard input,
  10994.  standard output, and standard error. The number of available handles set by
  10995.  the DosSetMaxFH function includes these handles. The DosOpenQueue, KbdOpen,
  10996.  and MouOpen functions also use these handles.
  10997.  
  10998.  
  10999.  See Also
  11000.  
  11001.  DosDupHandle, DosOpen, DosOpenQueue, KbdOpen, MouOpen
  11002.  
  11003.  
  11004.  Changes
  11005.  
  11006.  The maximum number of handles has been increased from 255 to 32,768.
  11007.  
  11008.  
  11009.  █    DosSetPathInfo
  11010.  ────────────────────────────────────────────────────────────────────────────
  11011.  
  11012.  USHORT DosSetPathInfo  (pszPathName, usInfoLevel, pInfoBuf, cbInfoBuf,
  11013.  fsOptions, ulReserved)
  11014.  
  11015.  PSZ  pszPathName;                 /*pointer to path */
  11016.  
  11017.  USHORT  usInfoLevel;              /*level of information */
  11018.  
  11019.  PBYTE  pInfoBuf;                  /*pointer to buffer for information */
  11020.  
  11021.  USHORT  cbInfoBuf;                /*length of information buffer */
  11022.  
  11023.  USHORT  fsOptions;                /*options */
  11024.  
  11025.  ULONG  ulReserved;                /*must be zero */
  11026.  
  11027.  
  11028.  The DosSetPathInfo function sets information for a specified file or
  11029.  directory.
  11030.  
  11031.  The DosSetPathInfo function is a family API function.
  11032.  
  11033.  
  11034.  Parameters
  11035.  
  11036.  pszPathName  Points to the null-terminated string that specifies the path of
  11037.  the file or directory. The string must be a valid MS OS/2 path.
  11038.  
  11039.  usInfoLevel  Specifies the level of information to set. This parameter can
  11040.  be one of the following values:
  11041.  
  11042.  Value                             Meaning
  11043.  ────────────────────────────────────────────────────────────────────────────
  11044.  
  11045.  FIL_STANDARD                      Use a FILESTATUS structure.
  11046.  
  11047.  FIL_QUERYEASIZE                   Use an EAOP structure to set extended
  11048.                                    attributes.
  11049.  
  11050.  
  11051.  
  11052.  pInfoBuf  Points to the buffer where path information is stored. The buffer
  11053.  contains a FILESTATUS structure for FIL_STANDARD information or an EAOP
  11054.  structure for FIL_QUERYEASIZE information.
  11055.  
  11056.  The FILESTATUS structure has the following form:
  11057.  
  11058.  typedef struct _FILESTATUS {
  11059.      FDATE  fdateCreation;
  11060.      FTIME  ftimeCreation;
  11061.      FDATE  fdateLastAccess;
  11062.      FTIME  ftimeLastAccess;
  11063.      FDATE  fdateLastWrite;
  11064.      FTIME  ftimeLastWrite;
  11065.      ULONG  cbFile;
  11066.      ULONG  cbFileAlloc;
  11067.      USHORT attrFile;
  11068.  } FILESTATUS;
  11069.  
  11070.  
  11071.  
  11072.  
  11073.  The EAOP structure has the following form:
  11074.  
  11075.  typedef struct _EAOP {
  11076.      PGEALIST fpGEAList;
  11077.      PFEALIST fpFEAList;
  11078.      ULONG    oError;
  11079.  } EAOP;
  11080.  
  11081.  
  11082.  
  11083.  
  11084.  For a full description, see Chapter 4, "Types, Macros, Structures."
  11085.  
  11086.  cbInfoBuf  Specifies the length (in bytes) of the buffer pointed to by the
  11087.  pInfoBuf parameter.
  11088.  
  11089.  fsOptions  Specifies one or more options. For MS OS/2 versions 1.2 and
  11090.  later, DSPI_WRTTHRU is the only available option. The DSPI_WRTTHRU option
  11091.  means all data, including extended attributes, must be written to the disk
  11092.  before the function returns.
  11093.  
  11094.  ulReserved  Specifies a reserved value; must be zero.
  11095.  
  11096.  
  11097.  Return Value
  11098.  
  11099.  
  11100.  
  11101.  The return value is zero if the function is successful. Otherwise, it is an
  11102.  error value, which may be one of the following:
  11103.  
  11104.       ERROR_BUFFER_OVERFLOW
  11105.       ERROR_EA_LIST_INCONSISTENT
  11106.       ERROR_FILENAME_EXCED_RANGE
  11107.       ERROR_INVALID_EA_NAME
  11108.       ERROR_INVALID_LEVEL
  11109.       ERROR_PATH_NOT_FOUND
  11110.  
  11111.  
  11112.  
  11113.  
  11114.  
  11115.  Comments
  11116.  
  11117.  If the DosSetPathInfo function is used to set extended-attribute
  11118.  information, the fpFEAList field of the EAOP structure should point to the
  11119.  FEALIST structure that contains the extended attributes. The fpGEAList field
  11120.  of the EAOP structure will be ignored.
  11121.  
  11122.  DosSetPathInfo fails if another process has the same file or directory.
  11123.  
  11124.  A zero value in both the date and time fields of an attribute cause those
  11125.  attributes to remain unchanged. For example, if both the fdateLastWrite and
  11126.  ftimeLastWrite fields of the FILESTATUS structure are zero, both attributes
  11127.  are unchanged. If either field is nonzero, both fields are set to the new
  11128.  values. If extended attributes are modified, the file's last modification
  11129.  date and time will be changed.
  11130.  
  11131.  
  11132.  See Also
  11133.  
  11134.  DosQPathInfo, DosSetFileInfo
  11135.  
  11136.  
  11137.  █    DosSetPrty
  11138.  ────────────────────────────────────────────────────────────────────────────
  11139.  
  11140.  USHORT DosSetPrty  (fScope, fPrtyClass, sChange, id)
  11141.  
  11142.  USHORT  fScope;                   /*scope of change */
  11143.  
  11144.  USHORT  fPrtyClass;               /*priority class to set */
  11145.  
  11146.  SHORT  sChange;                   /*change in priority level */
  11147.  
  11148.  USHORT  id;                       /*process or thread identifier */
  11149.  
  11150.  
  11151.  The DosSetPrty function sets the scheduling priority of the specified
  11152.  process or thread by changing the priority class and/or the priority level.
  11153.  
  11154.  Within each class, a thread's priority level may vary─either through system
  11155.  action or through the DosSetPrty function. The system changes a thread's
  11156.  priority level based on that thread's actions and the overall system
  11157.  activity.
  11158.  
  11159.  
  11160.  Parameters
  11161.  
  11162.  fScope  Specifies the scope of the request. This parameter can be one of the
  11163.  following values:
  11164.  
  11165.  Value                             Meaning
  11166.  ────────────────────────────────────────────────────────────────────────────
  11167.  
  11168.  PRTYS_PROCESS                     Priority for the process and all its
  11169.                                    threads.
  11170.  
  11171.  PRTYS_PROCESSTREE                 Priority for the process and all its
  11172.                                    child processes.
  11173.  
  11174.  PRTYS_THREAD                      Priority for one thread in the current
  11175.                                    process.
  11176.  
  11177.  
  11178.  
  11179.  fPrtyClass  Specifies the priority class of a process or thread. This
  11180.  parameter can be one of the following values:
  11181.  
  11182.  Value                             Meaning
  11183.  ────────────────────────────────────────────────────────────────────────────
  11184.  
  11185.  PRTYC_IDLETIME                    Idle time.
  11186.  
  11187.  PRTYC_NOCHANGE                    No change; leave as is.
  11188.  
  11189.  PRTYC_REGULAR                     Regular.
  11190.  
  11191.  PRTYC_FOREGROUND                  Foreground server.
  11192.  
  11193.  PRTYC_TIMECRITICAL                Time-critical.
  11194.  
  11195.  
  11196.  
  11197.  sChange  Specifies the relative change in the current priority level of the
  11198.  process or thread. This parameter can be any value from -31 through +31, or
  11199.  the constants PRTYD_MINIMUM or PRTYD_MAXIMUM, which specify the minimum and
  11200.  maximum change allowed.
  11201.  
  11202.  id  Specifies the process or thread identifier, depending on the value of
  11203.  the fScope parameter. If the value is a process identifier, it must be for
  11204.  the calling process or a child of the calling process. A value of zero can
  11205.  be used to specify the current thread or process.
  11206.  
  11207.  
  11208.  Return Value
  11209.  
  11210.  The return value is zero if the function is successful. Otherwise, it is an
  11211.  error value, which may be one of the following:
  11212.  
  11213.       ERROR_INVALID_PCLASS
  11214.       ERROR_INVALID_PDELTA
  11215.       ERROR_INVALID_PROCID
  11216.       ERROR_INVALID_SCOPE
  11217.       ERROR_INVALID_THREADID
  11218.       ERROR_NOT_DESCENDANT
  11219.  
  11220.  
  11221.  
  11222.  
  11223.  
  11224.  Comments
  11225.  
  11226.  The PRTYC_FOREGROUND priority is higher than PRTYC_REGULAR, but lower than
  11227.  PRTYC_TIMECRITICAL. PRTYC_FOREGROUND is a static priority that is not
  11228.  changed by the system. This allows a thread or process in a background
  11229.  screen group to service requests of a foreground process in a timely manner.
  11230.  Because the priority level is static, this priority should be used only when
  11231.  absolutely necessary. Indiscriminate use degrades system performance.
  11232.  
  11233.  
  11234.  See Also
  11235.  
  11236.  DosEnterCritSec, DosGetInfoSeg, DosGetPrty
  11237.  
  11238.  
  11239.  Changes
  11240.  
  11241.  A new value, PRTYC_FOREGROUND, can be specified for fPrtyClass.
  11242.  
  11243.  
  11244.  █    DosSetVec
  11245.  ────────────────────────────────────────────────────────────────────────────
  11246.  
  11247.  USHORT DosSetVec  (usVecNum, pfnFunction, ppfnPrev)
  11248.  
  11249.  USHORT  usVecNum;                 /*type of exception */
  11250.  
  11251.  PFN  pfnFunction;                 /*pointer to function */
  11252.  
  11253.  PPFN  ppfnPrev;                   /*pointer to variable for previous
  11254.                                    function's address */
  11255.  
  11256.  
  11257.  The DosSetVec function installs or removes an exception handler for a
  11258.  specified exception. An exception is a program error, such as division by
  11259.  zero, that causes the system to pass control to the exception handler. The
  11260.  exception handler is an assembly-language routine that corrects errors or
  11261.  cleans up programs before terminating. The system calls the exception
  11262.  handler whenever the specified exception occurs. If a process does not
  11263.  install its own exception handler, the default exception handler terminates
  11264.  the process when an exception occurs.
  11265.  
  11266.  The DosSetVec function is a family API function.
  11267.  
  11268.  
  11269.  Parameters
  11270.  
  11271.  usVecNum  Specifies the number of the exception vector. This parameter can
  11272.  be one of the following values:
  11273.  
  11274.  Value                             Meaning
  11275.  ────────────────────────────────────────────────────────────────────────────
  11276.  
  11277.  VECTOR_DIVIDE_BY_ZERO             Division by zero
  11278.  
  11279.  VECTOR_EXTENSION_ERROR            Processor extension error
  11280.  
  11281.  VECTOR_INVALIDOPCODE              Invalid operation code (opcode)
  11282.  
  11283.  VECTOR_NO_EXTENSION               Processor extension not available
  11284.  
  11285.  VECTOR_OUTOFBOUNDS                Out of bounds
  11286.  
  11287.  VECTOR_OVERFLOW                   Overflow
  11288.  
  11289.  
  11290.  
  11291.  pfnFunction  Points to the address of the exception handler that receives
  11292.  control when the specified exception occurs. If this parameter is zero, the
  11293.  DosSetVec function removes the current exception handler. For a full
  11294.  description, see the following "Comments" section.
  11295.  
  11296.  ppfnPrev  Points to the variable that receives the address of the previous
  11297.  exception handler. The new exception handler can use this address to chain
  11298.  exception handling through all previous handlers or to restore the previous
  11299.  exception handler.
  11300.  
  11301.  
  11302.  Return Value
  11303.  
  11304.  The return value is zero if the function is successful. Otherwise, it is an
  11305.  error value, which may be the following:
  11306.  
  11307.       ERROR_INVALID_FUNCTION
  11308.  
  11309.  
  11310.  
  11311.  
  11312.  
  11313.  Comments
  11314.  
  11315.  When the system calls the exception handler, it enables interrupts and
  11316.  pushes the machine status word and far return address on the stack. If the
  11317.  exception handler returns, it must use the iret (return-from-interrupt)
  11318.  instruction.
  11319.  
  11320.  If the DosSetVec function is used to install an exception handler for the
  11321.  vector VECTOR_EXTENSION_ERROR, the function sets the machine status word to
  11322.  indicate that no 80287 processor is available. The emulation bit is set and
  11323.  the monitor-processor bit is cleared. (This is done without regard for the
  11324.  true state of the hardware.) If the DosSetVec function is used to remove the
  11325.  exception handler for VECTOR_EXTENSION_ERROR, the function sets the machine
  11326.  status word to reflect the true state of the hardware.
  11327.  
  11328.  If the routine being registered is in a segment that has the iopl
  11329.  instruction indicated, the exception when it occurs, causes a general
  11330.  protection fault and the process is terminated.
  11331.  
  11332.  
  11333.  Restrictions
  11334.  
  11335.  In real mode, the following restriction applies to the DosSetVec function:
  11336.  
  11337.    ■   Because the 8086 and 8088 microprocessors do not raise this exception,
  11338.        usVecNum cannot be VECTOR_EXTENSION_ERROR.
  11339.  
  11340.  
  11341.  
  11342.  
  11343.  See Also
  11344.  
  11345.  DosDevConfig, DosError
  11346.  
  11347.  
  11348.  Corrections
  11349.  
  11350.  The exception handler must not be in an IOPL segment; otherwise the
  11351.  exception will cause a general protection fault.
  11352.  
  11353.  
  11354.  █    DosShutdown
  11355.  ────────────────────────────────────────────────────────────────────────────
  11356.  
  11357.  USHORT DosShutdown  (ulReserved)
  11358.  
  11359.  ULONG  ulReserved;                /*must be zero */
  11360.  
  11361.  
  11362.  The DosShutdown function flushes all system buffers and closes down the file
  11363.  system. After DosShutdown is called, no process can access the file system
  11364.  until the computer is rebooted.
  11365.  
  11366.  
  11367.  Parameters
  11368.  
  11369.  ulReserved  Specifies a reserved value; must be zero.
  11370.  
  11371.  
  11372.  Return Value
  11373.  
  11374.  The return value is zero if the function is successful. Otherwise, it is an
  11375.  error value, which may be the following:
  11376.  
  11377.       ERROR_INVALID_PARAMETER
  11378.  
  11379.  
  11380.  
  11381.  
  11382.  
  11383.  Comments
  11384.  
  11385.  The DosShutdown function may take as much as several minutes to return,
  11386.  depending on the amount of data being written to the disk.
  11387.  
  11388.  Because it is not possible to swap memory to the disk once the DosShutdown
  11389.  function has been called, some functions may fail due to a lack of memory in
  11390.  low memory situations. All memory that the calling process may need should
  11391.  be allocated before calling DosShutdown; this includes implicit memory
  11392.  allocation that may be done by system functions for the calling process.
  11393.  
  11394.  
  11395.  █    DosStartSession
  11396.  ────────────────────────────────────────────────────────────────────────────
  11397.  
  11398.  USHORT DosStartSession  (pstdata, pidSession, ppid)
  11399.  
  11400.  PSTARTDATA  pstdata;              /*pointer to structure with session data
  11401.                                    */
  11402.  
  11403.  PUSHORT  pidSession;              /*pointer to variable for session
  11404.                                    identifier */
  11405.  
  11406.  PUSHORT  ppid;                    /*pointer to variable for process
  11407.                                    identifier */
  11408.  
  11409.  
  11410.  The DosStartSession function starts a session (screen group) and specifies
  11411.  which program to start in that session. This function creates an independent
  11412.  session or a child session, depending on the value of the Related field in
  11413.  the STARTDATA structure.
  11414.  
  11415.  
  11416.  Parameters
  11417.  
  11418.  pstdata  Points to the STARTDATA structure that contains data describing the
  11419.  session to start. The STARTDATA structure has the following form:
  11420.  
  11421.  typedef struct _STARTDATA {
  11422.      USHORT Length;
  11423.      USHORT Related;
  11424.      USHORT FgBg;
  11425.      USHORT TraceOpt;
  11426.      PSZ    PgmTitle;
  11427.      PSZ    PgmName;
  11428.      PBYTE  PgmInputs;
  11429.      PBYTE  TermQ;
  11430.      PBYTE  Environment;
  11431.      USHORT InheritOpt;
  11432.      USHORT SessionType;
  11433.      PSZ    IconFile;
  11434.      ULONG  PgmHandle;
  11435.      USHORT PgmControl;
  11436.      USHORT InitXPos;
  11437.      USHORT InitYPos;
  11438.      USHORT InitXSize;
  11439.      USHORT InitYSize;
  11440.  } STARTDATA;
  11441.  
  11442.  
  11443.  
  11444.  
  11445.  For a full description, see Chapter 4, "Types, Macros, Structures."
  11446.  
  11447.  pidSession  Points to the variable that receives the identifier of the child
  11448.  session.
  11449.  
  11450.  ppid  Points to the variable that receives the process identifier of the
  11451.  child process.
  11452.  
  11453.  
  11454.  Return Value
  11455.  
  11456.  The return value is zero if the function is successful. Otherwise, it is an
  11457.  error value.
  11458.  
  11459.  
  11460.  Comments
  11461.  
  11462.  The MS OS/2 session manager writes a data element into the specified queue
  11463.  when the child session created by the DosStartSession function terminates. A
  11464.  parent session can be notified when a child session has terminated by using
  11465.  the DosReadQueue function. When the child session terminates, the request
  11466.  value returned by DosReadQueue is zero, and the data-element format consists
  11467.  of two unsigned values: the session identifier and the result code.
  11468.  
  11469.  Only the process that calls the DosStartSession function should call the
  11470.  DosReadQueue function. Only this process can address the notification data
  11471.  element. After reading and processing the data element, the calling process
  11472.  must use the DosFreeSeg function to free the segment that contains the data
  11473.  element.
  11474.  
  11475.  A child session is created when the Related field of the STARTDATA structure
  11476.  is set to TRUE.
  11477.  
  11478.  The process identifier of the child process cannot be used with MS OS/2
  11479.  functions, such as DosSetPrty, that require a parent process/child process
  11480.  relationship.
  11481.  
  11482.  An independent session is created when the Related field of the STARTDATA
  11483.  structure is set to FALSE. An independent session is not under the control
  11484.  of the starting session. The DosStartSession function does not copy session
  11485.  and process identifiers for an independent session to the pidSession and
  11486.  ppid parameters.
  11487.  
  11488.  New sessions can be started in the foreground only when the caller's session
  11489.  (or one of the caller's descendant sessions) is currently executing in the
  11490.  foreground. The new session appears in the shell switch list.
  11491.  
  11492.  
  11493.  See Also
  11494.  
  11495.  DosCreateQueue, DosExecPgm, DosFreeSeg, DosReadQueue, DosSelectSession,
  11496.  DosSetPrty, DosSetSession, DosStopSession
  11497.  
  11498.  
  11499.  Corrections
  11500.  
  11501.  The comments incorrectly stated that an independent session was created when
  11502.  the Related field of the STARTDATA structure is set to TRUE. The Related
  11503.  field must be set to FALSE to create an independent session.
  11504.  
  11505.  
  11506.  █    DosSubAlloc
  11507.  ────────────────────────────────────────────────────────────────────────────
  11508.  
  11509.  USHORT DosSubAlloc  (sel, pusOffset, cbBlock)
  11510.  
  11511.  SEL  sel;                         /*segment selector */
  11512.  
  11513.  PUSHORT  pusOffset;               /*pointer to variable for offset */
  11514.  
  11515.  USHORT  cbBlock;                  /*requested size of memory block */
  11516.  
  11517.  
  11518.  The DosSubAlloc function allocates memory in a segment that was allocated
  11519.  previously by using the DosAllocSeg or DosAllocShrSeg function and that was
  11520.  initialized by using the DosSubSet function.
  11521.  
  11522.  The DosSubAlloc function is a family API function.
  11523.  
  11524.  
  11525.  Parameters
  11526.  
  11527.  sel  Specifies the selector of the data segment in which the memory should
  11528.  be allocated.
  11529.  
  11530.  pusOffset  Points to the variable that receives the offset to the allocated
  11531.  block.
  11532.  
  11533.  cbBlock  Specifies the size (in bytes) of the requested memory block. This
  11534.  value should be a multiple of 4. If it is not, it will be rounded up. No
  11535.  check is made to determine whether this rounding will cause the allocation
  11536.  request to exceed the size of the segment.
  11537.  
  11538.  The cbBlock parameter must not be greater than the maximum size of the
  11539.  segment minus 8 bytes.
  11540.  
  11541.  
  11542.  Return Value
  11543.  
  11544.  The return value is zero if the function is successful. Otherwise, it is an
  11545.  error value, which may be one of the following:
  11546.  
  11547.       ERROR_DOSSUB_BADSIZE
  11548.       ERROR_DOSSUB_NOMEM
  11549.  
  11550.  
  11551.  
  11552.  
  11553.  
  11554.  Comments
  11555.  
  11556.  DosSubAlloc can be issued from ring 2 or ring 3; the suballocation segment
  11557.  can be either a ring-2 or a ring-3 segment.
  11558.  
  11559.  
  11560.  See Also
  11561.  
  11562.  DosAllocSeg, DosAllocShrSeg, DosSubFree, DosSubSet
  11563.  
  11564.  
  11565.  Corrections
  11566.  
  11567.  The cbBlock parameter should be a multiple of 4. If it is not, it will be
  11568.  rounded up. No check is made to determine whether this rounding will cause
  11569.  the allocation request to exceed the size of the segment.
  11570.  
  11571.  
  11572.  █    DosSubFree
  11573.  ────────────────────────────────────────────────────────────────────────────
  11574.  
  11575.  USHORT DosSubFree  (sel, offBlock, cbBlock)
  11576.  
  11577.  SEL  sel;                         /*segment selector */
  11578.  
  11579.  USHORT  offBlock;                 /*block offset */
  11580.  
  11581.  USHORT  cbBlock;                  /*number of bytes in block to free */
  11582.  
  11583.  
  11584.  The DosSubFree function frees memory that was allocated previously by using
  11585.  the DosSubAlloc function.
  11586.  
  11587.  The DosSubFree function is a family API function.
  11588.  
  11589.  
  11590.  Parameters
  11591.  
  11592.  sel  Specifies the selector of the data segment from which the memory should
  11593.  be freed.
  11594.  
  11595.  offBlock  Specifies the offset of the memory block to be freed. This offset
  11596.  must have been created previously by using the DosSubAlloc function.
  11597.  
  11598.  cbBlock  Specifies the size (in bytes) of the block to free. This parameter
  11599.  should be a multiple of 4. If it is not, it will be rounded up.
  11600.  
  11601.  
  11602.  Return Value
  11603.  
  11604.  The return value is zero if the function is successful. Otherwise, it is an
  11605.  error value, which may be one of the following:
  11606.  
  11607.       ERROR_DOSSUB_BADSIZE
  11608.       ERROR_DOSSUB_OVERLAP
  11609.  
  11610.  
  11611.  
  11612.  
  11613.  
  11614.  Comments
  11615.  
  11616.  DosSubFree can be issued from ring 2 or ring 3; and the suballocation
  11617.  segment can be either a ring-2 or a ring-3 segment.
  11618.  
  11619.  
  11620.  See Also
  11621.  
  11622.  DosAllocSeg, DosSubAlloc, DosSubSet
  11623.  
  11624.  
  11625.  Corrections
  11626.  
  11627.  The cbBlock parameter should be a multiple of 4. If it is not, it will be
  11628.  rounded up.
  11629.  
  11630.  
  11631.  █    DosSubSet
  11632.  ────────────────────────────────────────────────────────────────────────────
  11633.  
  11634.  USHORT DosSubSet  (sel, fFlags, cbSeg)
  11635.  
  11636.  SEL  sel;                         /*segment selector */
  11637.  
  11638.  USHORT  fFlags;                   /*initialize/increase size of segment */
  11639.  
  11640.  USHORT  cbSeg;                    /*new size of block */
  11641.  
  11642.  
  11643.  The DosSubSet function initializes a segment for suballocation or changes
  11644.  the size of a previously initialized segment.
  11645.  
  11646.  The DosSubSet function is a family API function.
  11647.  
  11648.  
  11649.  Parameters
  11650.  
  11651.  sel  Specifies the selector of the data segment.
  11652.  
  11653.  fFlags  Specifies whether to initialize the segment or increase its size. If
  11654.  this parameter is 0x0001, the function initializes the segment. If this
  11655.  parameter is 0x0000, the function changes the segment size.
  11656.  
  11657.  cbSeg  Specifies the new size (in bytes) of the segment. This size should be
  11658.  a multiple of 4. If it is not, it will be rounded up. A value of zero may be
  11659.  used to specify 64K. The minimum size that can be set is 12.
  11660.  
  11661.  
  11662.  Return Value
  11663.  
  11664.  The return value is zero if the function is successful. Otherwise, it is an
  11665.  error value, which may be one of the following:
  11666.  
  11667.       ERROR_DOSSUB_BADFLAG
  11668.       ERROR_DOSSUB_BADSIZE
  11669.       ERROR_DOSSUB_SHRINK
  11670.  
  11671.  
  11672.  
  11673.  
  11674.  
  11675.  Comments
  11676.  
  11677.  If the fFlags parameter is 0x0001, the DosSubSet function initializes the
  11678.  segment so that the DosSubAlloc function can be used to allocate memory
  11679.  blocks in the segment. The segment must have been allocated previously by
  11680.  using the DosAllocSeg or DosAllocShrSeg function.
  11681.  
  11682.  If the fFlags parameter is 0x0000, the DosSubSet function changes the
  11683.  segment size to the number of bytes specified by the cbSeg parameter. If the
  11684.  specified size is greater than the current segment size, the DosReallocSeg
  11685.  function must be called before DosSubSet. If DosSubSet is not called after
  11686.  changing the size of a segment by using DosReallocSeg, the results can be
  11687.  unpredictable.
  11688.  
  11689.  In the DosSubSet function, setting the cbSeg parameter to zero indicates
  11690.  that the segment size is 64K, but in the DosSubAlloc and DosSubFree
  11691.  functions, an error occurs when the cbSeg parameter is set to zero.
  11692.  
  11693.  DosSubSet can be issued from ring 2 or ring 3. The suballocation segment can
  11694.  be either a ring-2 or a ring-3 segment.
  11695.  
  11696.  
  11697.  See Also
  11698.  
  11699.  DosAllocSeg, DosAllocShrSeg, DosReallocSeg, DosSubAlloc, DosSubFree
  11700.  
  11701.  
  11702.  Corrections
  11703.  
  11704.  The cbSeg parameter should be a multiple of 4. If it is not, it will be
  11705.  rounded up. A value of zero may be used to specify 64K. The minimum size
  11706.  that can be set is 12.
  11707.  
  11708.  
  11709.  █    DosWaitNmPipe
  11710.  ────────────────────────────────────────────────────────────────────────────
  11711.  
  11712.  USHORT DosWaitNmPipe  (pszName, ulTimeOut)
  11713.  
  11714.  PSZ  pszName;                     /*pointer to pipe name */
  11715.  
  11716.  ULONG  ulTimeOut;                 /*time-out value */
  11717.  
  11718.  
  11719.  The DosWaitNmPipe function waits for a named pipe to become available.
  11720.  
  11721.  
  11722.  Parameters
  11723.  
  11724.  pszName  Points to the pipe name. The name is in the form \epipe\ename for a
  11725.  local pipe and \e\eserver\epipe\ename for a remote pipe.
  11726.  
  11727.  ulTimeOut  Specifies the amount of time (in milliseconds) MS OS/2 should
  11728.  wait for the pipe to become available. A value of NP_INDEFINITE_WAIT causes
  11729.  an infinite wait. A value of NP_DEFAULT_WAIT causes the system to wait for
  11730.  the default time specified by the call to the DosMakeNmPipe function that
  11731.  created this named pipe.
  11732.  
  11733.  
  11734.  Return Value
  11735.  
  11736.  The return value is zero if the function is successful. Otherwise, it is an
  11737.  error value, which may be one of the following:
  11738.  
  11739.       ERROR_BAD_PIPE
  11740.       ERROR_INTERRUPT
  11741.       ERROR_SEM_TIMEOUT
  11742.  
  11743.  
  11744.  
  11745.  
  11746.  
  11747.  Comments
  11748.  
  11749.  The DosWaitNmPipe function should be used only when the DosOpen function
  11750.  returns the ERROR_PIPE_BUSY error value.
  11751.  
  11752.  If more than one process has requested a named pipe that has become
  11753.  available, MS OS/2 gives the pipe to the process that has been waiting the
  11754.  longest.
  11755.  
  11756.  
  11757.  See Also
  11758.  
  11759.  DosOpen
  11760.  
  11761.  
  11762.  Corrections
  11763.  
  11764.  A value of NP_INDEFINITE_WAIT for the ulTimeOut parameter specifies an
  11765.  infinite wait; a value of NP_DEFAULT_WAIT for ulTimeOut uses the default
  11766.  time-out specified in the DosMakeNmPipe function.
  11767.  
  11768.  
  11769.  █    DosWrite
  11770.  ────────────────────────────────────────────────────────────────────────────
  11771.  
  11772.  USHORT DosWrite  (hf, pvBuf, cbBuf, pcbBytesWritten)
  11773.  
  11774.  HFILE  hf;                        /*file handle */
  11775.  
  11776.  PVOID  pvBuf;                     /*pointer to buffer */
  11777.  
  11778.  USHORT  cbBuf;                    /*number of bytes to write */
  11779.  
  11780.  PUSHORT  pcbBytesWritten;         /*pointer to variable receiving byte
  11781.                                    count */
  11782.  
  11783.  
  11784.  The DosWrite function writes data from a buffer to a file, then copies the
  11785.  number of bytes written to a variable.
  11786.  
  11787.  The DosWrite function is a family API function.
  11788.  
  11789.  
  11790.  Parameters
  11791.  
  11792.  hf  Identifies the file that receives the data. This handle must have been
  11793.  created by using the DosOpen function.
  11794.  
  11795.  pvBuf  Points to the buffer that contains the data to write.
  11796.  
  11797.  cbBuf  Specifies the number of bytes to write.
  11798.  
  11799.  pcbBytesWritten  Points to the variable receiving the number of bytes
  11800.  written.
  11801.  
  11802.  
  11803.  Return Value
  11804.  
  11805.  The return value is zero if the function is successful. Otherwise, it is an
  11806.  error value, which may be one of the following:
  11807.  
  11808.       ERROR_ACCESS_DENIED
  11809.       ERROR_BROKEN_PIPE
  11810.       ERROR_INVALID_HANDLE
  11811.       ERROR_LOCK_VIOLATION
  11812.       ERROR_NOT_DOS_DISK
  11813.       ERROR_WRITE_FAULT
  11814.  
  11815.  
  11816.  
  11817.  
  11818.  
  11819.  Comments
  11820.  
  11821.  The DosWrite function begins to write at the current file-pointer position.
  11822.  The file-pointer position can be changed by using the DosChgFilePtr
  11823.  function.
  11824.  
  11825.  If the specified file has been opened using the write-through flag, the
  11826.  DosWrite function writes data to the disk before returning. Otherwise, the
  11827.  system collects the data in an internal file buffer and writes the data to
  11828.  the disk only when the buffer is full.
  11829.  
  11830.  The DosWrite function may write fewer bytes to the file than the number
  11831.  specified in the cbBuf parameter if there is not enough space on the disk
  11832.  for all of the requested bytes. The cbBuf parameter can be zero without
  11833.  causing an error─that is, writing no bytes is acceptable.
  11834.  
  11835.  The efficiency with which DosWrite writes to a disk is improved when cbBuf
  11836.  is set to a multiple of the disk's bytes-per-sector size. When cbBuf is set
  11837.  this way, DosWrite writes directly to the disk, without first copying the
  11838.  data to an internal file buffer. (DosQFSInfo retrieves the bytes-per-sector
  11839.  value for a disk.)
  11840.  
  11841.  DosWrite can be used to write bytes or messages to a pipe. Each write to a
  11842.  message pipe writes a message whose size is the length of the write;
  11843.  DosWrite automatically encodes message lengths in the pipe, so applications
  11844.  need not encode this information in the buffer being written.
  11845.  
  11846.  Writes in blocking mode always write all requested bytes before returning.
  11847.  In nonblocking mode, writes return either with all bytes written or none
  11848.  written; the latter will occur in cases where DosWrite would have to block
  11849.  in order to complete the request─for example, if there is no room in the
  11850.  pipe buffer or if the buffer is currently being written to by another
  11851.  client.
  11852.  
  11853.  An attempt to write to a pipe whose other end has been closed will return
  11854.  the error ERROR_BROKEN_PIPE.
  11855.  
  11856.  
  11857.  Example
  11858.  
  11859.  This example creates the file abc and calls the DosWrite function to write
  11860.  the contents of the abBuf buffer to the file:
  11861.  
  11862.  BYTE abBuf[512];
  11863.  HFILE hf;
  11864.  USHORT usAction, cbBytesWritten, usError;
  11865.  usError = DosOpen("abc", &hf, &usAction, 0L, FILE_NORMAL,
  11866.      FILE_CREATE,
  11867.      OPEN_ACCESS_WRITEONLY | OPEN_SHARE_DENYWRITE, 0L);
  11868.  if (!usError) {
  11869.      DosWrite(hf,                  /* file handle              */
  11870.          abBuf,                    /* buffer address           */
  11871.          sizeof(abBuf),            /* buffer size              */
  11872.          &cbBytesWritten);         /* address of bytes written */
  11873.  
  11874.  
  11875.  
  11876.  
  11877.  
  11878.  See Also
  11879.  
  11880.  DosChgFilePtr, DosOpen, DosQFSInfo, DosRead, DosWriteAsync
  11881.  
  11882.  
  11883.  Corrections
  11884.  
  11885.  DosWrite can be used to write bytes or messages to a pipe. Relevant
  11886.  information about writing to a named pipe has been added.
  11887.  
  11888.  
  11889.  █    DosWriteAsync
  11890.  ────────────────────────────────────────────────────────────────────────────
  11891.  
  11892.  USHORT DosWriteAsync  (hf, hsemRam, pusErrCode, pvBuf, cbBuf,
  11893.  pcbBytesWritten)
  11894.  
  11895.  HFILE  hf;                        /*file handle */
  11896.  
  11897.  PULONG  hsemRam;                  /*pointer to RAM semaphore */
  11898.  
  11899.  PUSHORT  pusErrCode;              /*pointer to variable for error value */
  11900.  
  11901.  PVOID  pvBuf;                     /*pointer to buffer containing data to
  11902.                                    write */
  11903.  
  11904.  USHORT  cbBuf;                    /*number of bytes in buffer */
  11905.  
  11906.  PUSHORT  pcbBytesWritten;         /*pointer to variable for bytes written
  11907.                                    */
  11908.  
  11909.  
  11910.  The DosWriteAsync function writes one or more bytes of data to a specified
  11911.  file. The function writes the data asynchronously─that is, the function
  11912.  returns immediately, but continues to copy data to the specified file while
  11913.  the process continues with other tasks.
  11914.  
  11915.  
  11916.  Parameters
  11917.  
  11918.  hf  Identifies the file that receives the data. This handle must have been
  11919.  created previously by using the DosOpen function.
  11920.  
  11921.  hsemRam  Points to the RAM semaphore that indicates when the function has
  11922.  finished reading the data.
  11923.  
  11924.  pusErrCode  Points to the variable that receives an error value.
  11925.  
  11926.  pvBuf  Points to the buffer that contains the data to write.
  11927.  
  11928.  cbBuf  Specifies the number of bytes to write.
  11929.  
  11930.  pcbBytesWritten  Points to the variable receiving the number of bytes
  11931.  written.
  11932.  
  11933.  
  11934.  Return Value
  11935.  
  11936.  The return value is zero if the function is successful. Otherwise, it is an
  11937.  error value, which may be one of the following:
  11938.  
  11939.       ERROR_ACCESS_DENIED
  11940.       ERROR_BROKEN_PIPE
  11941.       ERROR_INVALID_HANDLE
  11942.       ERROR_LOCK_VIOLATION
  11943.       ERROR_NO_PROC_SLOTS
  11944.       ERROR_NOT_DOS_DISK
  11945.       ERROR_WRITE_FAULT
  11946.  
  11947.  
  11948.  
  11949.  
  11950.  
  11951.  Comments
  11952.  
  11953.  The DosWriteAsync function starts writing at the current file-pointer
  11954.  position. The file-pointer position can be changed by using the
  11955.  DosChgFilePtr function.
  11956.  
  11957.  If the specified file has been opened using the write-through flag, the
  11958.  DosWriteAsync function writes data to an internal file buffer and to the
  11959.  disk before returning. If the write-through flag has not been set, the
  11960.  system collects the data in an internal file buffer and writes the data to
  11961.  the disk only when the buffer is full.
  11962.  
  11963.  The DosWriteAsync function may write fewer bytes to the file than the number
  11964.  specified in the cbBuf parameter if there is not enough space on the disk
  11965.  for all the requested bytes. The cbBuf parameter can be zero without causing
  11966.  an error─that is, writing no bytes is acceptable.
  11967.  
  11968.  When the DosWriteAsync function has written the data, it clears the RAM
  11969.  semaphore pointed to by the hsemRam parameter. If the process uses the
  11970.  semaphore to determine when data is available, it must use the DosSemSet
  11971.  function to set the semaphore before calling DosWriteAsync.
  11972.  
  11973.  The efficiency with which the DosWriteAsync function writes to a disk is
  11974.  improved when the cbBuf parameter is set to a multiple of the disk's
  11975.  bytes-per-sector size. When cbBuf is set this way, the function writes
  11976.  directly to the disk, without first copying the data to an internal file
  11977.  buffer. (The DosQFSInfo function retrieves the bytes-per-sector value for a
  11978.  disk.)
  11979.  
  11980.  DosWriteAsync can be used to write bytes or messages to a pipe. Each write
  11981.  to a message pipe writes a message whose size is specified by the cbBuf
  11982.  parameter; DosWriteAsync automatically encodes message lengths in the pipe,
  11983.  so applications need not encode this information in the buffer being
  11984.  written.
  11985.  
  11986.  In blocking mode, write operations always write all requested bytes before
  11987.  returning. In nonblocking mode, write operations return either with all
  11988.  bytes written or none written; the latter occurs in cases where
  11989.  DosWriteAsync has to block in order to complete the request (for example, if
  11990.  there is no room in the pipe buffer or if the buffer is currently being
  11991.  written to by another process).
  11992.  
  11993.  When the function tries to write to a pipe whose other end has been closed,
  11994.  it returns the error ERROR_BROKEN_PIPE.
  11995.  
  11996.  
  11997.  Example
  11998.  
  11999.  This example creates the file abc.ext, sets a RAM semaphore, and calls the
  12000.  DosWriteAsync function to write the contents of the buffer abBuf to a file.
  12001.  When any additional processing is finished, the example calls the DosSemWait
  12002.  function to wait until DosWriteAsync has finished writing to the file.
  12003.  
  12004.  ULONG hsemWrite = 0;
  12005.  BYTE abBuf[1024];
  12006.  HFILE hf;
  12007.  USHORT usAction, cbBytesWritten;
  12008.  USHORT usWriteAsyncError;
  12009.  DosOpen("abc.ext", &hf, &usAction, 0L, FILE_NORMAL,
  12010.      FILE_CREATE,
  12011.      OPEN_ACCESS_WRITEONLY | OPEN_SHARE_DENYWRITE, 0L);
  12012.  
  12013.  DosSemSet(&hsemWrite);         /* sets semaphore           */
  12014.  DosWriteAsync(hf,              /* file handle              */
  12015.      &hsemWrite,                /* semaphore address        */
  12016.      &usWriteAsyncError,        /* return-code address      */
  12017.      abBuf,                     /* buffer address           */
  12018.      sizeof(abBuf),             /* buffer size              */
  12019.      &cbBytesWritten);          /* address of bytes written */
  12020.      .
  12021.      . /* Other processing would go here. */
  12022.      .
  12023.  DosSemWait(&hsemWrite, -1L);   /* waits for DosWriteAsync  */
  12024.  if (usWriteAsyncError) {
  12025.      .
  12026.      . /* Error processing would go here. */
  12027.      .
  12028.  
  12029.  
  12030.  
  12031.  
  12032.  
  12033.  See Also
  12034.  
  12035.  DosChgFilePtr, DosOpen, DosQFSInfo, DosReadAsync, DosSemSet, DosSemWait,
  12036.  DosWrite
  12037.  
  12038.  
  12039.  Corrections
  12040.  
  12041.  Information about using DosWriteAsync with named pipes has been added.
  12042.  
  12043.  
  12044.  █    DosWriteQueue
  12045.  ────────────────────────────────────────────────────────────────────────────
  12046.  
  12047.  USHORT DosWriteQueue  (hqueue, usRequest, cbBuf, pbBuf, usPriority)
  12048.  
  12049.  HQUEUE  hqueue;                   /*target-queue handle */
  12050.  
  12051.  USHORT  usRequest;                /*request/identification data */
  12052.  
  12053.  USHORT  cbBuf;                    /*number of bytes to write */
  12054.  
  12055.  PBYTE  pbBuf;                     /*pointer to buffer with element to
  12056.                                    write */
  12057.  
  12058.  UCHAR  usPriority;                /*priority of element to write */
  12059.  
  12060.  
  12061.  The DosWriteQueue function writes an element to the specified queue. The
  12062.  position of the element in the queue is determined by the value specified in
  12063.  the fQueueOrder parameter of the DosCreateQueue function when the queue was
  12064.  created; if this parameter was set to 0x0002 (priority queue), the
  12065.  usPriority parameter of the DosWriteQueue function can be used to set the
  12066.  priority of the element. After the element is written, the process that owns
  12067.  the queue can read the element by using the DosPeekQueue or DosReadQueue
  12068.  function.
  12069.  
  12070.  
  12071.  Parameters
  12072.  
  12073.  hqueue  Identifies the queue to be written to. This handle must have been
  12074.  created or opened by using the DosCreateQueue or DosOpenQueue function.
  12075.  
  12076.  usRequest  Specifies a program-supplied event code. MS OS/2 does not use
  12077.  this field; it is reserved for the program's use. The queue owner can
  12078.  retrieve this value by using the DosPeekQueue or DosReadQueue function.
  12079.  
  12080.  cbBuf  Specifies the number of bytes to be copied from the buffer pointed to
  12081.  by the pbBuf parameter.
  12082.  
  12083.  pbBuf  Points to the buffer that contains the element to be written to the
  12084.  queue.
  12085.  
  12086.  usPriority  Specifies the element priority. This parameter can be any value
  12087.  from 0 through 15; 15 is the highest priority.
  12088.  
  12089.  
  12090.  Return Value
  12091.  
  12092.  The return value is zero if the function is successful. Otherwise, it is an
  12093.  error value, which may be one of the following:
  12094.  
  12095.       ERROR_QUE_INVALID_HANDLE
  12096.       ERROR_QUE_NO_MEMORY
  12097.  
  12098.  
  12099.  
  12100.  
  12101.  
  12102.  Comments
  12103.  
  12104.  The DosWriteQueue function returns an error value if the queue has been
  12105.  closed by the process that owns it.
  12106.  
  12107.  If the queue owner uses a RAM semaphore to notify it when elements are added
  12108.  to the queue, the semaphore must be shared. If the notifying semaphore is a
  12109.  system semaphore, the writing process must have opened the semaphore by
  12110.  using the DosOpenSem function.
  12111.  
  12112.  
  12113.  Example
  12114.  
  12115.  This example opens a queue called \equeues\equeuename. In order to write to
  12116.  the queue, the process allocates shared memory, gives the memory to the
  12117.  queue owner, copies data to the shared memory, and calls DosWriteQueue. The
  12118.  process then frees the shared memory. The queue owner must also free the
  12119.  shared memory before it becomes available to the system again. For more
  12120.  information, see DosReadQueue.
  12121.  
  12122.  PID pidOwner;
  12123.  SEL sel, selRecipient;
  12124.  
  12125.  DosOpenQueue(&pidOwner, &hqueue,
  12126.      "\\queues\\queuename");                /* opens queue             */
  12127.  DosAllocSeg(512, &sel, SEG_GIVEABLE);      /* allocates shared memory */
  12128.  DosGiveSeg(sel, pidOwner, &selRecipient);  /* gives it to queue owner */
  12129.      .
  12130.      . /* Copy the data to the shared memory segment. */
  12131.      .
  12132.         DosWriteQueue(hqueue,    /* queue handle                */
  12133.             0,                   /* request data                */
  12134.             11,                  /* length of data              */
  12135.      MAKEP(selRecipient, 0),     /* data buffer                 */
  12136.             0);                  /* element priority            */
  12137.         DosFreeSeg(sel);         /* frees shared memory segment */
  12138.  
  12139.  
  12140.  
  12141.  
  12142.  
  12143.  See Also
  12144.  
  12145.  DosCreateQueue, DosOpenQueue, DosOpenSem, DosPeekQueue, DosReadQueue
  12146.  
  12147.  
  12148.  Corrections
  12149.  
  12150.  The example worked only for interthread communication. It has been replaced
  12151.  with an example that works for interprocess communication.
  12152.  
  12153.  The description of the cbBuf parameter incorrectly stated that this
  12154.  parameter contained the number of bytes to be written to the buffer. It now
  12155.  correctly states that this is the number of bytes to be written from the
  12156.  buffer.
  12157.  
  12158.  
  12159.  █    EM_QUERYREADONLY
  12160.  ────────────────────────────────────────────────────────────────────────────
  12161.  
  12162.  
  12163.  EM_QUERYREADONLY
  12164.  mp1 = 0L;    /* not used, must be zero */
  12165.  mp2 = 0L;    /* not used, must be zero */
  12166.  
  12167.  
  12168.  An application sends the EM_QUERYREADONLY message to retrieve the read-only
  12169.  state of an entry field.
  12170.  
  12171.  
  12172.  Parameters
  12173.  
  12174.  This message does not use any parameters.
  12175.  
  12176.  
  12177.  Return Value
  12178.  
  12179.  The return value is TRUE if the read-only state is set; otherwise it is
  12180.  FALSE.
  12181.  
  12182.  
  12183.  See Also
  12184.  
  12185.  EM_SETREADONLY
  12186.  
  12187.  
  12188.  █    EM_SETINSERTMODE
  12189.  ────────────────────────────────────────────────────────────────────────────
  12190.  
  12191.  
  12192.  EM_SETINSERTMODE
  12193.  mp1 = MPFROMSHORT(fInsertMode);    /* insert-mode flag       */
  12194.  mp2 = 0L;                          /* not used, must be zero */
  12195.  
  12196.  
  12197.  An application sends the EM_SETINSERTMODE message to set or clear the system
  12198.  insert-mode state.
  12199.  
  12200.  
  12201.  Parameters
  12202.  
  12203.  fInsertMode  Low word of mp1. Specifies whether to set or clear the insert
  12204.  mode. If this parameter is TRUE, insert mode is turned on; if it is FALSE,
  12205.  insert mode is turned off.
  12206.  
  12207.  
  12208.  Return Value
  12209.  
  12210.  The return value is TRUE if the previous insert mode was on or FALSE if the
  12211.  previous insert mode was off.
  12212.  
  12213.  
  12214.  Comments
  12215.  
  12216.  This message changes the SV_INSERTMODE system constant to reflect the
  12217.  current insert-mode state. It also sends an EN_INSERTMODETOGGLE notification
  12218.  message.
  12219.  
  12220.  
  12221.  See Also
  12222.  
  12223.  EN_INSERTMODETOGGLE
  12224.  
  12225.  
  12226.  █    EM_SETREADONLY
  12227.  ────────────────────────────────────────────────────────────────────────────
  12228.  
  12229.  
  12230.  EM_SETREADONLY
  12231.  mp1 = MPFROMSHORT(fReadOnly);    /* read-only state        */
  12232.  mp2 = 0L;                        /* not used, must be zero */
  12233.  
  12234.  
  12235.  An application sends the EM_SETREADONLY message to set the read-only state
  12236.  of an entry field.
  12237.  
  12238.  
  12239.  Parameters
  12240.  
  12241.  fReadOnly  Low word of mp1. Specifies whether to set or remove the read-only
  12242.  state of the entry field. A value of TRUE sets the state.
  12243.  
  12244.  
  12245.  Return Value
  12246.  
  12247.  The return value is TRUE if the read-only state is set; otherwise, it is
  12248.  FALSE.
  12249.  
  12250.  
  12251.  Comments
  12252.  
  12253.  When the read-only state of an entry field is set, the user cannot change
  12254.  the text within the entry field.
  12255.  
  12256.  
  12257.  See Also
  12258.  
  12259.  EM_QUERYREADONLY
  12260.  
  12261.  
  12262.  █    EM_SETTEXTLIMIT
  12263.  ────────────────────────────────────────────────────────────────────────────
  12264.  
  12265.  
  12266.  EM_SETTEXTLIMIT
  12267.  mp1 = MPFROMSHORT((SHORT) cchMax);    /* max. number of bytes   */
  12268.  mp2 = 0L;                             /* not used, must be zero */
  12269.  
  12270.  
  12271.  An application sends an EM_SETTEXTLIMIT message to set the maximum number of
  12272.  bytes an entry-field control can contain.
  12273.  
  12274.  
  12275.  Parameters
  12276.  
  12277.  cchMax  Low word of mp1. Specifies the maximum number of bytes an entry
  12278.  field can hold.
  12279.  
  12280.  
  12281.  Return Value
  12282.  
  12283.  The return value is TRUE if the operation is successful or FALSE if there is
  12284.  not enough memory to hold the requested number of characters.
  12285.  
  12286.  
  12287.  Comments
  12288.  
  12289.  Sending an EM_SETTEXTLIMIT message causes memory to be allocated from the
  12290.  control heap for the specified maximum number of bytes. Failure to allocate
  12291.  sufficient memory results in a WM_CONTROL message, with the EN_MEMERROR
  12292.  notification code being sent to the owner window.
  12293.  
  12294.  
  12295.  See Also
  12296.  
  12297.  WM_CONTROL
  12298.  
  12299.  
  12300.  Changes
  12301.  
  12302.  All references to characters have been replaced by bytes to accommodate
  12303.  systems in which a character may be composed of more than one byte.
  12304.  
  12305.  
  12306.  █    EN_CHANGE
  12307.  ────────────────────────────────────────────────────────────────────────────
  12308.  
  12309.  
  12310.  WM_CONTROL
  12311.  id = (USHORT) SHORT1FROMMP(mp1);    /* control-window ID            */
  12312.  usNotifyCode = EN_CHANGE;
  12313.  hwndEdit = HWNDFROMMP(mp2);         /* window handle of entry field */
  12314.  
  12315.  
  12316.  The EN_CHANGE notification message is sent when the text in an entry field
  12317.  changes.
  12318.  
  12319.  
  12320.  Parameters
  12321.  
  12322.  id  Low word of mp1. Identifies the control window.
  12323.  
  12324.  usNotifyCode  High word of mp1. Set to EN_CHANGE.
  12325.  
  12326.  hwndEdit  Low and high words of mp2. Identifies the entry-field window.
  12327.  
  12328.  
  12329.  Return Value
  12330.  
  12331.  An application should return zero if it processes this message.
  12332.  
  12333.  
  12334.  See Also
  12335.  
  12336.  WM_CONTROL
  12337.  
  12338.  
  12339.  █    EN_INSERTMODETOGGLE
  12340.  ────────────────────────────────────────────────────────────────────────────
  12341.  
  12342.  
  12343.  WM_CONTROL
  12344.  id = (USHORT) SHORT1FROMMP(mp1);    /* control-window ID            */
  12345.  usNotifyCode = EN_INSERTMODETOGGLE;
  12346.  hwndEdit = HWNDFROMMP(mp2);         /* window handle of entry field */
  12347.  
  12348.  
  12349.  The EN_INSERTMODETOGGLE notification message is sent when the insert mode of
  12350.  an entry-field control is toggled.
  12351.  
  12352.  
  12353.  Parameters
  12354.  
  12355.  id  Low word of mp1. Identifies the control window.
  12356.  
  12357.  usNotifyCode  High word of mp1. Set to EN_INSERTMODETOGGLE.
  12358.  
  12359.  hwndEdit  Low and high words of mp2. Identifies the entry-field window.
  12360.  
  12361.  
  12362.  Return Value
  12363.  
  12364.  An application should return zero if it processes this message.
  12365.  
  12366.  
  12367.  See Also
  12368.  
  12369.  EM_SETINSERTMODE, WM_CONTROL
  12370.  
  12371.  
  12372.  █    EN_KILLFOCUS
  12373.  ────────────────────────────────────────────────────────────────────────────
  12374.  
  12375.  
  12376.  WM_CONTROL
  12377.  id = (USHORT) SHORT1FROMMP(mp1);    /* control-window ID            */
  12378.  usNotifyCode = EN_KILLFOCUS;
  12379.  hwndEdit = HWNDFROMMP(mp2);         /* window handle of entry field */
  12380.  
  12381.  
  12382.  The EN_KILLFOCUS notification message is sent when an entry-field control
  12383.  loses the input focus.
  12384.  
  12385.  
  12386.  Parameters
  12387.  
  12388.  id  Low word of mp1. Identifies the control window.
  12389.  
  12390.  usNotifyCode  High word of mp1. Set to EN_KILLFOCUS.
  12391.  
  12392.  hwndEdit  Low and high words of mp2. Identifies the entry-field window.
  12393.  
  12394.  
  12395.  See Also
  12396.  
  12397.  EN_SETFOCUS, WM_CONTROL
  12398.  
  12399.  
  12400.  █    EN_MEMERROR
  12401.  ────────────────────────────────────────────────────────────────────────────
  12402.  
  12403.  
  12404.  WM_CONTROL
  12405.  id = (USHORT) SHORT1FROMMP(mp1);    /* control-window ID            */
  12406.  usNotifyCode = EN_MEMERROR;
  12407.  hwndEdit = HWNDFROMMP(mp2);         /* window handle of entry field */
  12408.  
  12409.  
  12410.  The EN_MEMERROR notification message is sent when an entry-field control
  12411.  cannot allocate the memory necessary to accommodate window text of the
  12412.  length specified by the EM_SETTEXTLIMIT message.
  12413.  
  12414.  
  12415.  Parameters
  12416.  
  12417.  id  Low word of mp1. Identifies the control window.
  12418.  
  12419.  usNotifyCode  High word of mp1. Set to EN_MEMERROR.
  12420.  
  12421.  hwndEdit  Low and high words of mp2. Identifies the entry-field window.
  12422.  
  12423.  
  12424.  See Also
  12425.  
  12426.  EM_SETTEXTLIMIT, WM_CONTROL
  12427.  
  12428.  
  12429.  █    EN_OVERFLOW
  12430.  ────────────────────────────────────────────────────────────────────────────
  12431.  
  12432.  
  12433.  WM_CONTROL
  12434.  id = (USHORT) SHORT1FROMMP(mp1);    /* control-window ID            */
  12435.  usNotifyCode = EN_OVERFLOW;
  12436.  hwndEdit = HWNDFROMMP(mp2);         /* window handle of entry field */
  12437.  
  12438.  
  12439.  The EN_OVERFLOW notification message is sent when the text limit in an entry
  12440.  field is exceeded.
  12441.  
  12442.  
  12443.  Parameters
  12444.  
  12445.  id  Low word of mp1. Identifies the control window.
  12446.  
  12447.  usNotifyCode  High word of mp1. Set to EN_OVERFLOW.
  12448.  
  12449.  hwndEdit  Low and high words of mp2. Identifies the entry-field window.
  12450.  
  12451.  
  12452.  Return Value
  12453.  
  12454.  An application should return TRUE to retry the operation.
  12455.  
  12456.  
  12457.  See Also
  12458.  
  12459.  WM_CONTROL
  12460.  
  12461.  
  12462.  █    EN_SCROLL
  12463.  ────────────────────────────────────────────────────────────────────────────
  12464.  
  12465.  
  12466.  EN_SCROLL
  12467.  id = (USHORT) SHORT1FROMMP(mp1);    /* control-window ID            */
  12468.  usNotifyCode = EN_SCROLL;
  12469.  hwndEdit = HWNDFROMMP(mp2);         /* window handle of entry field */
  12470.  
  12471.  
  12472.  The EN_SCROLL notification message is sent to the owner of the entry-field
  12473.  window when a scroll-bar event occurs.
  12474.  
  12475.  
  12476.  Parameters
  12477.  
  12478.  id  Low word of mp1. Identifies the control window.
  12479.  
  12480.  usNotifyCode  High word of mp1. Set to EN_SCROLL.
  12481.  
  12482.  hwndEdit  Low and high words of mp2. Identifies the entry-field window.
  12483.  
  12484.  
  12485.  Return Value
  12486.  
  12487.  An application should return zero if it processes this message.
  12488.  
  12489.  
  12490.  See Also
  12491.  
  12492.  WM_CONTROL
  12493.  
  12494.  
  12495.  █    EN_SETFOCUS
  12496.  ────────────────────────────────────────────────────────────────────────────
  12497.  
  12498.  
  12499.  WM_CONTROL
  12500.  id = (USHORT) SHORT1FROMMP(mp1);    /* control-window ID            */
  12501.  usNotifyCode = EN_SETFOCUS;
  12502.  hwndEdit = HWNDFROMMP(mp2);         /* window handle of entry field */
  12503.  
  12504.  
  12505.  The EN_SETFOCUS notification message notifies an application when an entry
  12506.  field receives the input focus.
  12507.  
  12508.  
  12509.  Parameters
  12510.  
  12511.  id  Low word of mp1. Identifies the control window.
  12512.  
  12513.  usNotifyCode  High word of mp1. Set to EN_SETFOCUS.
  12514.  
  12515.  hwndEdit  Low and high words of mp2. Identifies the entry-field window.
  12516.  
  12517.  
  12518.  See Also
  12519.  
  12520.  EN_KILLFOCUS, WM_CONTROL
  12521.  
  12522.  
  12523.  █    Entry-Field-Control Styles
  12524.  ────────────────────────────────────────────────────────────────────────────
  12525.  
  12526.  
  12527.  
  12528.  The following style constants, specified when the entry-field control is
  12529.  created, determine its behavior and appearance:
  12530.  
  12531.  Style                             Description
  12532.  ────────────────────────────────────────────────────────────────────────────
  12533.  
  12534.  ES_ANY                            Allows the entry-field text to contain a
  12535.                                    mixture of double-byte and single-byte
  12536.                                    characters.
  12537.  
  12538.  ES_AUTOSCROLL                     Horizontally scrolls text automatically
  12539.                                    to show the insertion point.
  12540.  
  12541.  ES_AUTOTAB                        Automatically moves the cursor to the
  12542.                                    next control when the user enters the
  12543.                                    maximum number of characters.
  12544.  
  12545.  ES_CENTER                         Centers text in the entry field.
  12546.  
  12547.  ES_DBCS                           Specifies that the entry-field text is
  12548.                                    double-byte characters only.
  12549.  
  12550.  ES_LEFT                           Left-aligns text in the entry field.
  12551.  
  12552.  ES_MARGIN                         Draws a border around the entry-field
  12553.                                    control. The border is one-half
  12554.                                    character wide and one-fourth character
  12555.                                    high. Without this style, the control is
  12556.                                    drawn without a border. The entry-field
  12557.                                    rectangle is outset on all sides by this
  12558.                                    margin. After an ES_MARGIN entry field
  12559.                                    is created, the WinQueryWindowRect
  12560.                                    function returns a larger rectangle that
  12561.                                    includes this margin, and whose origin
  12562.                                    is therefore different from the one
  12563.                                    specified when the rectangle was created.
  12564.                                    Your application must adjust for this
  12565.                                    size difference when the user moves or
  12566.                                    sizes the entry-field control or else
  12567.                                    the control will become larger after
  12568.                                    each moving or sizing operation.
  12569.  
  12570.  ES_MIXED                          Allows the entry-field text to contain a
  12571.                                    mixture of single-byte and double-byte
  12572.                                    characters. Unlike the ES_ANY style,
  12573.                                    this style allows ASCII DBCS data to be
  12574.                                    converted to EBCDIC DBCS data without
  12575.                                    causing an overflow condition.
  12576.  
  12577.  ES_READONLY                       Prevents the user from entering or
  12578.                                    editing text in the entry field.
  12579.  
  12580.  ES_RIGHT                          Right-aligns text in the entry field.
  12581.  
  12582.  ES_SBCS                           Specifies that the entry-field text is
  12583.                                    single-byte characters only.
  12584.  
  12585.  ES_UNREADABLE                     Displays each character in the entry
  12586.                                    field as an asterisk.
  12587.  
  12588.  
  12589.  
  12590.  Changes
  12591.  
  12592.  The following new constants have been added:
  12593.  
  12594.      ES_ANY
  12595.      ES_AUTOTAB
  12596.      ES_DBCS
  12597.      ES_MIXED
  12598.      ES_READONLY
  12599.      ES_SBCS
  12600.      ES_UNREADABLE
  12601.  
  12602.  
  12603.  
  12604.  
  12605.  
  12606.  █    GpiCallSegmentMatrix
  12607.  ────────────────────────────────────────────────────────────────────────────
  12608.  
  12609.  LONG GpiCallSegmentMatrix  (hps, idSegment, cElements, pmatlf, lType)
  12610.  
  12611.  HPS  hps;                         /*presentation-space handle */
  12612.  
  12613.  LONG  idSegment;                  /*segment identifier */
  12614.  
  12615.  LONG  cElements;                  /*number of matrix elements to examine
  12616.                                    */
  12617.  
  12618.  PMATRIXLF  pmatlf;                /*address of structure for matrix */
  12619.  
  12620.  LONG  lType;                      /*transformation modifier */
  12621.  
  12622.  
  12623.  The GpiCallSegmentMatrix function draws the specified segment using an
  12624.  instance transformation. The function combines the instance transformation
  12625.  pointed to by pmatlf with the current model transformation, then draws the
  12626.  segment as if calling the GpiDrawSegment function. The combined
  12627.  transformation applies only while the function draws the segment.
  12628.  GpiCallSegmentMatrix does not modify the current model transformation.
  12629.  
  12630.  
  12631.  Parameters
  12632.  
  12633.  hps  Identifies the presentation space.
  12634.  
  12635.  idSegment  Specifies the segment to draw. This value must be greater than
  12636.  zero.
  12637.  
  12638.  cElements  Specifies the number of matrix elements pointed to by pmatlf. It
  12639.  can be any value from 0 through 9.
  12640.  
  12641.  pmatlf  Points to a MATRIXLF structure that contains the matrix for the
  12642.  instance transformation. Although a transformation requires nine matrix
  12643.  elements, the function copies from the structure only the number of matrix
  12644.  elements specified by cElements. If cElements is less than nine, the
  12645.  function supplies the remaining elements by substituting corresponding
  12646.  elements from the identity matrix.
  12647.  
  12648.  The MATRIXLF structure has the following form:
  12649.  
  12650.  typedef struct _MATRIXLF {
  12651.      FIXED fxM11;
  12652.      FIXED fxM12;
  12653.      LONG  lM13;
  12654.      FIXED fxM21;
  12655.      FIXED fxM22;
  12656.      LONG  lM23;
  12657.      LONG  lM31;
  12658.      LONG  lM32;
  12659.      LONG  lM33;
  12660.  } MATRIXLF;
  12661.  
  12662.  
  12663.  
  12664.  
  12665.  For a full description, see Chapter 4, "Types, Macros, Structures."
  12666.  
  12667.  lType  Specifies how to combine the instance transformation with the model
  12668.  transformation. It can be one of the following values:
  12669.  
  12670.  Value                             Meaning
  12671.  ────────────────────────────────────────────────────────────────────────────
  12672.  
  12673.  TRANSFORM_ADD                     Adds the model transformation to the
  12674.                                    instance transformation (MODEL *
  12675.                                    INSTANCE).
  12676.  
  12677.  TRANSFORM_PREEMPT                 Adds the instance transformation to the
  12678.                                    model transformation (INSTANCE * MODEL).
  12679.  
  12680.  TRANSFORM_REPLACE                 Replaces the model transform with the
  12681.                                    instance transformation.
  12682.  
  12683.  
  12684.  
  12685.  Return Value
  12686.  
  12687.  The return value is GPI_OK or GPI_HITS if the function is successful (it is
  12688.  GPI_HITS if the detectable attribute is set for the presentation space and a
  12689.  correlation hit occurs). The return value is GPI_ERROR if an error occurs.
  12690.  
  12691.  
  12692.  Errors
  12693.  
  12694.  Use the WinGetLastError function to retrieve the error value, which may be
  12695.  one of the following:
  12696.  
  12697.       PMERR_CALLED_SEG_IS_CURRENT
  12698.       PMERR_CALLED_SEG_NOT_FOUND
  12699.       PMERR_INV_HPS
  12700.       PMERR_INV_LENGTH_OR_COUNT
  12701.       PMERR_INV_MATRIX_ELEMENT
  12702.       PMERR_INV_MICROPS_FUNCTION
  12703.       PMERR_INV_SEG_NAME
  12704.       PMERR_INV_TRANSFORM_TYPE
  12705.       PMERR_PS_BUSY
  12706.       PMERR_SEG_CALL_RECURSIVE
  12707.       PMERR_SEG_NOT_FOUND
  12708.  
  12709.  
  12710.  
  12711.  
  12712.  
  12713.  Example
  12714.  
  12715.  This example calls the GpiCallSegmentMatrix function to draw a segment three
  12716.  times. Each time the segment is drawn, the instance transformation doubles
  12717.  in size. The result is three triangles with the last triangle twice the size
  12718.  of the second, and the second twice the size of the first.
  12719.  
  12720.  POINTL ptlStart = { 0, 0 };
  12721.  POINTL ptlTriangle[] = { 100, 100, 200, 0, 0, 0 };
  12722.  MATRIXLF matlfInstance = { MAKEFIXED(1, 0),  MAKEFIXED(0, 0), 0,
  12723.                             MAKEFIXED(0, 0),  MAKEFIXED(1, 0), 0,
  12724.                             0,                0,               1 };
  12725.  
  12726.  GpiOpenSegment(hps, 1L);             /* opens segment               */
  12727.  GpiMove(hps, &ptlStart);             /* moves to start point (0, 0) */
  12728.  GpiPolyLine(hps, 3L, ptlTriangle);   /* draws triangle              */
  12729.  GpiCloseSegment(hps);                /* closes segment              */
  12730.  
  12731.  for (i = 0; i < 3; i++) {
  12732.  
  12733.      /*
  12734.       * Draw the segment after adding the matrix to the model
  12735.       * transformation.
  12736.       */
  12737.  
  12738.      GpiCallSegmentMatrix(hps, 1L, 9, &matlfInstance, TRANSFORM_ADD);
  12739.      matlfInstance.fxM11 *= 2;
  12740.      matlfInstance.fxM22 *= 2;
  12741.  }
  12742.  
  12743.  
  12744.  
  12745.  
  12746.  
  12747.  
  12748.  See Also
  12749.  
  12750.  GpiDrawSegment
  12751.  
  12752.  
  12753.  Corrections
  12754.  
  12755.  In the example, the MAKEFIXED macro is required to create FIXED values for
  12756.  initializing the structure.
  12757.  
  12758.  
  12759.  █    GpiCreateLogFont
  12760.  ────────────────────────────────────────────────────────────────────────────
  12761.  
  12762.  LONG GpiCreateLogFont  (hps, pchName, lcid, pfat)
  12763.  
  12764.  HPS  hps;                         /*presentation-space handle */
  12765.  
  12766.  PSTR8  pchName;                   /*address of logical-font name */
  12767.  
  12768.  LONG  lcid;                       /*local identifier */
  12769.  
  12770.  PFATTRS  pfat;                    /*address of structure for font
  12771.                                    attributes */
  12772.  
  12773.  
  12774.  The GpiCreateLogFont function creates a logical font. A logical font is a
  12775.  list of font attributes, such as face name, average width, and maximum
  12776.  height, that an application uses to request a physical font. A physical font
  12777.  is the bitmap or vector information the system uses to draw characters on a
  12778.  device. Applications create logical fonts to specify the fonts they need,
  12779.  and the system maps the logical fonts to matching physical fonts.
  12780.  
  12781.  GpiCreateLogFont creates a logical font using the font attributes specified
  12782.  in the structure pointed to by the pfat parameter. Each logical font has a
  12783.  local identifier and logical font name, specified by the lcid and pchName
  12784.  parameters, to uniquely identify it. The local identifier can then be used
  12785.  in subsequent graphics functions to identify the font.
  12786.  
  12787.  Since a physical font that exactly matches the logical font may not be
  12788.  available, the system usually maps the logical font to the closest matching
  12789.  physical font. The system uses rules to map the font─for example, it chooses
  12790.  a font with a greater height if a font of the exact height is not available.
  12791.  An application can force the system to choose a particular font by setting
  12792.  the value of the lMatch field in the FATTRS structure to be that returned
  12793.  for the desired font by the GpiQueryFonts function. After GpiCreateLogFont
  12794.  chooses the physical font, this choice does not change for a particular
  12795.  logical font.
  12796.  
  12797.  
  12798.  Parameters
  12799.  
  12800.  hps  Identifies the presentation space.
  12801.  
  12802.  pchName  Points to an 8-character logical-font name. It can be NULL, if no
  12803.  logical font name is desired.
  12804.  
  12805.  lcid  Specifies the local identifier that the application uses to refer to
  12806.  this font. It must be in the range 1 through 254. It is an error if this
  12807.  parameter is already in use to refer to a font or bitmap.
  12808.  
  12809.  pfat  Points to a FATTRS structure that will contain the attributes of the
  12810.  logical font that is created. The FATTRS structure has the following form:
  12811.  
  12812.  typedef struct _FATTRS {
  12813.      USHORT  usRecordLength;
  12814.      USHORT  fsSelection;
  12815.      LONG    lMatch;
  12816.      CHAR    szFaceName[FACESIZE];
  12817.      USHORT  idRegistry;
  12818.      USHORT  usCodePage;
  12819.      LONG    lMaxBaselineExt;
  12820.      LONG    lAveCharWidth;
  12821.      USHORT  fsType;
  12822.      SHORT   sQuality;
  12823.      USHORT  fsFontUse;
  12824.  } FATTRS;
  12825.  
  12826.  
  12827.  
  12828.  
  12829.  For a full description, see Chapter 4, "Types, Macros, Structures."
  12830.  
  12831.  
  12832.  Return Value
  12833.  
  12834.  The return value is FONT_MATCH if a matching font is found, FONT_DEFAULT if
  12835.  a matching font could not be found, or zero if an error occurred.
  12836.  
  12837.  
  12838.  Errors
  12839.  
  12840.  Use the WinGetLastError function to retrieve the error value, which may be
  12841.  one of the following:
  12842.  
  12843.       PMERR_FONT_NOT_LOADED
  12844.       PMERR_INV_FONT_ATTRS
  12845.       PMERR_INV_HPS
  12846.       PMERR_INV_SETID
  12847.       PMERR_KERNING_NOT_SUPPORTED
  12848.       PMERR_PS_BUSY
  12849.       PMERR_SETID_IN_USE
  12850.  
  12851.  
  12852.  
  12853.  
  12854.  
  12855.  Comments
  12856.  
  12857.  To choose the system default font, set the face name to NULL and all other
  12858.  attributes in the FATTRS structure, except the code page, to zero.
  12859.  
  12860.  To use a font, the application sets the font for the presentation space by
  12861.  specifying the local identifier for the corresponding logical font with the
  12862.  GpiSetCharSet function. Once a font is set, the system uses the font for
  12863.  subsequent text output.
  12864.  
  12865.  
  12866.  Example
  12867.  
  12868.  This example uses the GpiCreateLogFont function to create a logical font
  12869.  with the local identifier 1. The logical font has the face name "Courier"
  12870.  and requested width and height of 12 pels. Once the font is created, the
  12871.  example sets the font using the local identifier and displays a string in
  12872.  the font at the point (100,100).
  12873.  
  12874.  USHORT i;
  12875.  POINTL ptl = { 100, 100 };
  12876.  FATTRS fat;
  12877.  
  12878.  fat.usRecordLength = sizeof(FATTRS); /* sets size of structure      */
  12879.  fat.fsSelection = 0;            /* uses default selection           */
  12880.  fat.lMatch = 0L;                /* does not force match             */
  12881.  fat.idRegistry = 0;             /* uses default registry            */
  12882.  fat.usCodePage = 850;           /* code-page 850                    */
  12883.  fat.lMaxBaselineExt = 12L;      /* requested font height is 12 pels */
  12884.  fat.lAveCharWidth = 12L;        /* requested font width is 12 pels  */
  12885.  fat.fsType = 0;                 /* uses default type                */
  12886.  fat.fsFontUse = FATTR_FONTUSE_NOMIX; /* does not mix with graphics  */
  12887.  
  12888.  /* Copy Courier to szFacename field. */
  12889.  
  12890.  for (i=0; fat.szFacename[i] = "Courier"[i]; i++);
  12891.  
  12892.  
  12893.  GpiCreateLogFont(hps,           /* presentation space               */
  12894.                   (PSTR8) NULL,  /* does not use logical font name   */
  12895.                   1L,            /* local identifier                 */
  12896.                   &fat);         /* structure with font attributes   */
  12897.  
  12898.  GpiSetCharSet(hps, 1L);         /* sets font for presentation space */
  12899.  GpiCharStringAt(hps, &ptl, 5L, "Hello"); /* displays a string       */
  12900.  
  12901.  
  12902.  
  12903.  
  12904.  
  12905.  See Also
  12906.  
  12907.  GpiCharStringAt, GpiCreateLogFont, GpiQueryFonts, GpiSetCharSet
  12908.  
  12909.  
  12910.  Corrections
  12911.  
  12912.  In the example, the fat.fsType field should be set to 0 rather than to
  12913.  FATTR_TYPE_FIXED.
  12914.  
  12915.  
  12916.  █    GpiDestroyPS
  12917.  ────────────────────────────────────────────────────────────────────────────
  12918.  
  12919.  BOOL GpiDestroyPS  (hps)
  12920.  
  12921.  HPS  hps;                         /*presentation-space handle */
  12922.  
  12923.  
  12924.  The GpiDestroyPS function destroys the presentation space and releases all
  12925.  resources owned by the presentation space. This function should only be used
  12926.  to destroy presentation spaces created by the GpiCreatePS function.
  12927.  
  12928.  
  12929.  Parameters
  12930.  
  12931.  hps  Identifies the presentation space.
  12932.  
  12933.  
  12934.  Return Value
  12935.  
  12936.  The return value is GPI_OK if the function is successful or GPI_ERROR if an
  12937.  error occurred.
  12938.  
  12939.  
  12940.  Errors
  12941.  
  12942.  Use the WinGetLastError function to retrieve the error value, which may be
  12943.  one of the following:
  12944.  
  12945.       PMERR_INV_HPS
  12946.       PMERR_PS_BUSY
  12947.       PMERR_PS_IS_ASSOCIATED
  12948.  
  12949.  
  12950.  
  12951.  
  12952.  
  12953.  Example
  12954.  
  12955.  This example uses the GpiDestroyPS function to destroy the presentation
  12956.  space associated with a memory device context.
  12957.  
  12958.  HDC hdc;
  12959.  HPS hps;
  12960.  SIZEL page = { 0, 0 };
  12961.  
  12962.  /* Create the memory device context and presentation space. */
  12963.  
  12964.  hdc = DevOpenDC(hab, OD_MEMORY, "*", 0L, (PDEVOPENDATA) NULL, (HDC) NULL);
  12965.  hps = GpiCreatePS(hab, hdc, &page, PU_PELS | GPIT_MICRO | GPIA_ASSOC);
  12966.      .
  12967.      .
  12968.      .
  12969.  GpiAssociate(hps, (HDC) NULL);
  12970.  GpiDestroyPS(hps);    /* destroys presentation space */
  12971.  DevCloseDC(hdc);      /* closes device context       */
  12972.  
  12973.  
  12974.  
  12975.  
  12976.  
  12977.  See Also
  12978.  
  12979.  GpiCreatePS
  12980.  
  12981.  
  12982.  Corrections
  12983.  
  12984.  In the example, GpiAssociate must be called before DevCloseDC. This is true
  12985.  whenever a device context is associated with a presentation space.
  12986.  
  12987.  
  12988.  █    GpiGetData
  12989.  ────────────────────────────────────────────────────────────────────────────
  12990.  
  12991.  LONG GpiGetData  (hps, idSegment, poff, cmdFormat, cb, pb)
  12992.  
  12993.  HPS  hps;                         /*presentation-space handle */
  12994.  
  12995.  LONG  idSegment;                  /*segment identifier */
  12996.  
  12997.  PLONG  poff;                      /*address of variable for segment offset
  12998.                                    */
  12999.  
  13000.  LONG  cmdFormat;                  /*conversion type */
  13001.  
  13002.  LONG  cb;                         /*length in bytes of the data buffer */
  13003.  
  13004.  PBYTE  pb;                        /*address of buffer for data */
  13005.  
  13006.  
  13007.  The GpiGetData function copies graphics orders from the specified segment to
  13008.  the specified buffer. The function continues to copy the graphics orders
  13009.  from the segment to the buffer until all orders in the segment have been
  13010.  copied or the number of bytes specified by the cb parameter have been
  13011.  copied. If the function fills the buffer, the last order in the buffer may
  13012.  not be complete since the function does not stop on an order boundary when
  13013.  copying to the buffer. In any case, the function returns the number of bytes
  13014.  copied to the buffer.
  13015.  
  13016.  The function starts copying graphics-order data from the location specified
  13017.  by the poff parameter. If this parameter is zero, the function copies from
  13018.  the beginning of the segment. After copying the data, the function replaces
  13019.  the value in poff with the offset to the next byte of data to copy from the
  13020.  segment (if any). This value can be used to specify the next location to
  13021.  copy.
  13022.  
  13023.  The GpiGetData function cannot be used to copy data from an open segment,
  13024.  but it can be used to copy data while some other segment is open.
  13025.  
  13026.  
  13027.  Parameters
  13028.  
  13029.  hps  Identifies the presentation space.
  13030.  
  13031.  idSegment  Specifies the segment identifier.
  13032.  
  13033.  poff  Points to the variable that contains the offset from the beginning of
  13034.  the segment to the next byte of graphics order data to copy. If this
  13035.  parameter is zero, the function copies from the beginning of the segment.
  13036.  
  13037.  cmdFormat  Specifies the coordinate conversion type. It can be one of the
  13038.  following values:
  13039.  
  13040.  Value                             Meaning
  13041.  ────────────────────────────────────────────────────────────────────────────
  13042.  
  13043.  DFORM_NOCONV                      Copies coordinates without converting.
  13044.                                    The coordinates are in the format used
  13045.                                    by the presentation space.
  13046.  
  13047.  DFORM_PCLONG                      Converts coordinates to PC-format long
  13048.                                    (4-byte) integers.
  13049.  
  13050.  DFORM_PCSHORT                     Converts coordinates to PC-format short
  13051.                                    (2-byte) integers.
  13052.  
  13053.  DFORM_S370SHORT                   Converts coordinates to S/370-format
  13054.                                    short (2-byte) integers.
  13055.  
  13056.  
  13057.  
  13058.  cb  Specifies the length in bytes of the buffer to receive the graphics
  13059.  orders.
  13060.  
  13061.  pb  Points to the buffer that receives the graphics-order data.
  13062.  
  13063.  
  13064.  Return Value
  13065.  
  13066.  The return value is the number of graphics-order bytes copied if the
  13067.  function is successful or GPI_ALTERROR if an error occurred.
  13068.  
  13069.  
  13070.  Errors
  13071.  
  13072.  Use the WinGetLastError function to retrieve the error value, which may be
  13073.  one of the following:
  13074.  
  13075.       PMERR_DATA_TOO_LONG
  13076.       PMERR_INV_GETDATA_CONTROL
  13077.       PMERR_INV_HPS
  13078.       PMERR_INV_LENGTH
  13079.       PMERR_INV_LENGTH_OR_COUNT
  13080.       PMERR_INV_MICROPS_FUNCTION
  13081.       PMERR_INV_SEG_NAME
  13082.       PMERR_INV_SEG_OFFSET
  13083.       PMERR_PS_BUSY
  13084.       PMERR_SEG_IS_CURRENT
  13085.       PMERR_SEG_NOT_FOUND
  13086.  
  13087.  
  13088.  
  13089.  
  13090.  
  13091.  Example
  13092.  
  13093.  This example uses the GpiGetData function to copy data from one segment to
  13094.  another.
  13095.  
  13096.  LONG fFormat = DFORM_NOCONV;     /* does not convert coordinates      */
  13097.  LONG offSegment = 0L;            /* offset in segment                 */
  13098.  LONG offNextElement = 0L;        /* offset in segment to next element */
  13099.  LONG cb = 0L;                    /* bytes retrieved                   */
  13100.  BYTE abBuffer[512];
  13101.  
  13102.  GpiOpenSegment(hps, 3L);         /* opens segment to receive data     */
  13103.  do {
  13104.      offSegment += cb;
  13105.      offNextElement = offSegment;
  13106.      cb = GpiGetData(hps, 2L, &offNextElement, fFormat, 512L, abBuffer);
  13107.  
  13108.      /* Put data in other segment. */
  13109.  
  13110.      if (cb > 0L) GpiPutData(hps, /* presentation-space handle         */
  13111.          fFormat,                 /* format of coordinates             */
  13112.          &cb,                     /* number of bytes in buffer         */
  13113.          abBuffer);               /* buffer with graphics-order data   */
  13114.  
  13115.  } while (cb > 0);
  13116.  GpiCloseSegment(hps);            /* closes segment that received data */
  13117.  
  13118.  
  13119.  
  13120.  
  13121.  
  13122.  See Also
  13123.  
  13124.  GpiPutData
  13125.  
  13126.  
  13127.  Corrections
  13128.  
  13129.  The poff parameter is a pointer to the variable that contains the offset;
  13130.  the cmdFormat parameter is an integer that specifies the conversion format.
  13131.  
  13132.  
  13133.  █    GpiLoadFonts
  13134.  ────────────────────────────────────────────────────────────────────────────
  13135.  
  13136.  BOOL GpiLoadFonts  (hab, pszFileName)
  13137.  
  13138.  HAB  hab;                         /*anchor-block handle */
  13139.  
  13140.  PSZ  pszFileName;                 /*pointer to filename */
  13141.  
  13142.  
  13143.  The GpiLoadFonts function loads fonts from the specified resource file. Once
  13144.  loaded, the fonts are private fonts and can be used by any thread in the
  13145.  process. Any other process can use the fonts but only if it also loads the
  13146.  font by using the GpiLoadFonts. The function loads a copy of the fonts once
  13147.  only. Any subsequent call to the function by another process for the same
  13148.  fonts simply increments the use count for the resource and gives that
  13149.  process access.
  13150.  
  13151.  
  13152.  Parameters
  13153.  
  13154.  hab  Identifies the anchor block.
  13155.  
  13156.  pszFileName  Points to a null-terminated string. This string must be a valid
  13157.  MS OS/2 filename. If it does not specify a path and the filename extension,
  13158.  the function appends the default extension (.dll) and searches for the font
  13159.  resource file in the directories specified by the libpath command in the
  13160.  config.sys file.
  13161.  
  13162.  
  13163.  Return Value
  13164.  
  13165.  The return value is GPI_OK if the function is successful or GPI_ERROR if an
  13166.  error occurred.
  13167.  
  13168.  
  13169.  Error
  13170.  
  13171.  Use the WinGetLastError function to retrieve the error value, which may be
  13172.  the following:
  13173.  
  13174.       PMERR_INV_FONT_FILE_DATA
  13175.  
  13176.  
  13177.  
  13178.  
  13179.  
  13180.  Example
  13181.  
  13182.  This example uses the GpiLoadFonts function to load all fonts from the font
  13183.  resource file helv.dll. The GpiQueryFonts function retrieves the number of
  13184.  fonts loaded.
  13185.  
  13186.  LONG cFonts = 0L;
  13187.  
  13188.  GpiLoadFonts(hab, "helv");
  13189.  cFonts = GpiQueryFonts(hps, QF_PRIVATE, (PSZ) NULL, &cFonts, 0L,
  13190.      (PFONTMETRICS) NULL);
  13191.  
  13192.  
  13193.  
  13194.  
  13195.  
  13196.  See Also
  13197.  
  13198.  GpiCreateLogFont, GpiDeleteSetId, GpiQueryFonts, GpiUnloadFonts
  13199.  
  13200.  
  13201.  Corrections
  13202.  
  13203.  In the example, the function loads fonts from the helv.dll file, not the
  13204.  helv.fon file. If no path and filename extension are given, the function by
  13205.  default searches for a file that has the .dll extension.
  13206.  
  13207.  
  13208.  █    GpiOutlinePath
  13209.  ────────────────────────────────────────────────────────────────────────────
  13210.  
  13211.  LONG GpiOutlinePath  (hps, lPath, lOptions)
  13212.  
  13213.  HPS  hps;                         /*presentation-space handle */
  13214.  
  13215.  LONG  lPath;                      /*identifies path to be outlined */
  13216.  
  13217.  LONG  lOptions;                   /*reserved, must be zero */
  13218.  
  13219.  
  13220.  The GpiOutlinePath function draws an outline of a path using the current
  13221.  line attributes. This function draws the outline such that each line, curve,
  13222.  and other item in the path appears to be drawn individually; it does not
  13223.  close the path. GpiOutlinePath draws the path using the current cosmetic
  13224.  line width (see the GpiSetLineWidth function); it does not fill the path.
  13225.  GpiOutlinePath deletes the path after drawing the outline.
  13226.  
  13227.  
  13228.  Parameters
  13229.  
  13230.  hps  Identifies the presentation space.
  13231.  
  13232.  lPath  Identifies the path to be outlined. For MS OS/2 versions 1.2 and
  13233.  later, this parameter must be set to 1.
  13234.  
  13235.  lOptions  Specifies outline options. For MS OS/2 versions 1.2 and later,
  13236.  this parameter must be set to zero.
  13237.  
  13238.  
  13239.  Return Value
  13240.  
  13241.  The return value is GPI_OK if the function is successful or GPI_ERROR if an
  13242.  error occurs.
  13243.  
  13244.  
  13245.  Errors
  13246.  
  13247.  Use the WinGetLastError function to retrieve the error value, which may be
  13248.  one of the following:
  13249.  
  13250.       PMERR_INV_HPS
  13251.       PMERR_INV_PATH_ID
  13252.       PMERR_INV_RESERVED_FIELD
  13253.       PMERR_PATH_UNKNOWN
  13254.       PMERR_PS_BUSY
  13255.  
  13256.  
  13257.  
  13258.  
  13259.  
  13260.  Comments
  13261.  
  13262.  If character strings are in the path, the function draws the outline of each
  13263.  character but does not fill the interior of the character, giving the
  13264.  appearance of hollow characters. For small characters, outlining in this way
  13265.  can give a visual appearance similar to filled characters, but with improved
  13266.  performance.
  13267.  
  13268.  
  13269.  See Also
  13270.  
  13271.  GpiBeginPath, GpiEndPath, GpiSetLineWidth
  13272.  
  13273.  
  13274.  █    GpiPlayMetaFile
  13275.  ────────────────────────────────────────────────────────────────────────────
  13276.  
  13277.  LONG GpiPlayMetaFile  (hps, hmf, cOptions, alOptions, pcSegments, cchDesc,
  13278.  pszDesc)
  13279.  
  13280.  HPS  hps;                         /*presentation-space handle */
  13281.  
  13282.  HMF  hmf;                         /*metafile handle */
  13283.  
  13284.  LONG  cOptions;                   /*number of elements in array */
  13285.  
  13286.  PLONG  alOptions;                 /*address of array of load options */
  13287.  
  13288.  PLONG  pcSegments;                /*address of count of renumbered
  13289.                                    segments */
  13290.  
  13291.  LONG  cchDesc;                    /*number of bytes in record */
  13292.  
  13293.  PSZ  pszDesc;                     /*address of buffer for descriptive
  13294.                                    record */
  13295.  
  13296.  
  13297.  The GpiPlayMetaFile function plays the metafile specified by the hmf
  13298.  parameter. The function plays the metafile file by converting the graphics
  13299.  data in the file to graphics operations for the given presentation space.
  13300.  The function uses the load options specified by the alOptions parameter to
  13301.  determine how to prepare the presentation space for playing the metafile.
  13302.  This may include resetting the presentation space, replacing tagged bitmaps
  13303.  and logical fonts, and replacing the logical color table.
  13304.  
  13305.   Since the metafile may create segments, the application must close any open
  13306.  segment before calling GpiPlayMetaFile. If the metafile creates segments,
  13307.  the function retains the segments only if the current drawing mode is
  13308.  DM_RETAIN or DM_DRAWANDRETAIN. If chained segments are retained, the
  13309.  function adds them to the end of the existing segment chain.
  13310.  
  13311.  The GpiPlayMetaFile function can play a metafile any number of times.
  13312.  
  13313.  
  13314.  Parameters
  13315.  
  13316.  hps  Identifies a presentation space.
  13317.  
  13318.  hmf  Identifies the metafile to play. It must have been created or loaded
  13319.  previously by using the DevOpenDC or GpiLoadMetaFile function.
  13320.  
  13321.  cOptions  Specifies the number of elements in the array pointed to by the
  13322.  alOptions parameter.
  13323.  
  13324.  alOptions  Points to the array specifying the load options. For a full
  13325.  description, see the following "Comments" section.
  13326.  
  13327.  pcSegments  Points to a variable for the count of renumbered segments. This
  13328.  parameter is reserved and is set to zero.
  13329.  
  13330.  cchDesc  Specifies the number of bytes in the buffer pointed to by the
  13331.  pszDesc parameter.
  13332.  
  13333.  pszDesc  Points to the buffer that receives the null-terminated string
  13334.  describing the metafile. This descriptive record is the record set by the
  13335.  DevOpenDC function for the metafile. If the buffer is smaller than the
  13336.  record, the function truncates the record.
  13337.  
  13338.  
  13339.  Return Value
  13340.  
  13341.  The return value is GPI_OK or GPI_HITS if the function is successful (it is
  13342.  GPI_HITS if the detectable attribute is set for the presentation space and a
  13343.  correlation hit occurs). The return value is GPI_ERROR if an error occurs.
  13344.  
  13345.  
  13346.  Errors
  13347.  
  13348.  Use the WinGetLastError function to retrieve the error value, which may be
  13349.  one of the following values:
  13350.  
  13351.       PMERR_INCOMPATIBLE_METAFILE
  13352.       PMERR_INV_ELEMENT_POINTER
  13353.       PMERR_INV_HMF
  13354.       PMERR_INV_HPS
  13355.       PMERR_INV_IN_CURRENT_EDIT_MODE
  13356.       PMERR_INV_LENGTH
  13357.       PMERR_INV_LENGTH_OR_COUNT
  13358.       PMERR_INV_METAFILE
  13359.       PMERR_INV_MICROPS_ORDER
  13360.       PMERR_INV_OUTSIDE_DRAW_MODE
  13361.       PMERR_INV_PLAY_METAFILE_OPTION
  13362.       PMERR_PROLOG_ERROR
  13363.       PMERR_PS_BUSY
  13364.       PMERR_STOP_DRAW_OCCURRED
  13365.  
  13366.  
  13367.  
  13368.  
  13369.  
  13370.  Comments
  13371.  
  13372.  The GpiPlayMetaFile function uses several options to control how a metafile
  13373.  is played. The options are specified in an array passed to the function by
  13374.  using the alOptions parameter. The array has at most ten elements, and there
  13375.  are eight predefined array indexes that can be used to access these
  13376.  elements. The following describes the purpose and possible values for each
  13377.  element:
  13378.  
  13379.  PMF_SEGBASE  Specifies a reserved element. It must be zero.
  13380.  
  13381.  PMF_LOADTYPE  Specifies the transformation to use when playing the metafile.
  13382.  It can be one of the following values:
  13383.  
  13384.  Value                             Meaning
  13385.  ────────────────────────────────────────────────────────────────────────────
  13386.  
  13387.  LT_DEFAULT                        Default; same as LT_NOMODIFY.
  13388.  
  13389.  LT_NOMODIFY                       Use the current viewing transformation
  13390.                                    as set by the application by using the
  13391.                                    GpiSetViewingTransformMatrix function.
  13392.                                    This is the default action.
  13393.  
  13394.  LT_ORIGINALVIEW                   Use the viewing transformations defined
  13395.                                    in the metafile.
  13396.  
  13397.  
  13398.  
  13399.  PMF_RESOLVE  Specifies a reserved element. It must be RS_DEFAULT or
  13400.  RS_NODISCARD.
  13401.  
  13402.  PMF_LCIDS  Specifies whether to use tagged bitmaps and logical fonts from
  13403.  the metafile or from the application. It can be one of the following values:
  13404.  
  13405.  
  13406.  Value                             Meaning
  13407.  ────────────────────────────────────────────────────────────────────────────
  13408.  
  13409.  LC_DEFAULT                        Default; same as LC_NOLOAD.
  13410.  
  13411.  LC_NOLOAD                         Use the tagged bitmaps and logical fonts
  13412.                                    defined by the application. The
  13413.                                    application must define the appropriate
  13414.                                    objects and local identifiers before
  13415.                                    playing the metafile. This is the
  13416.                                    default.
  13417.  
  13418.  LC_LOADDISC                       Use the tagged bitmaps and logical fonts
  13419.                                    defined in the metafile. The function
  13420.                                    loads the object from the metafile and
  13421.                                    assigns a local identifier. If the local
  13422.                                    identifier is already defined by the
  13423.                                    application, the function deletes the
  13424.                                    identifier before creating the new
  13425.                                    object.
  13426.  
  13427.  
  13428.  
  13429.  PMF_RESET  Specifies whether the presentation space should be reset before
  13430.  playing the metafile, with the page units and size being set as defined in
  13431.  the metafile. It can be one of the following values:
  13432.  
  13433.  Value                             Meaning
  13434.  ────────────────────────────────────────────────────────────────────────────
  13435.  
  13436.  RES_DEFAULT                       Default; same as RES_NORESET.
  13437.  
  13438.  RES_NORESET                       Does not reset the presentation space.
  13439.  
  13440.  RES_RESET                         Resets the presentation space. The
  13441.                                    function resets the page units and page
  13442.                                    size to the values specified by the
  13443.                                    metafile. It then sets up default
  13444.                                    transformations, based on page units and
  13445.                                    size, as if the presentation space had
  13446.                                    just been created with these values, and
  13447.                                    modifies the device transformation (if
  13448.                                    necessary) to ensure that the physical
  13449.                                    size of the metafile picture is
  13450.                                    preserved. Finally, it resets the
  13451.                                    presentation space as if calling the
  13452.                                    GpiResetPS function with the GRES_ALL
  13453.                                    option.
  13454.  
  13455.  
  13456.  
  13457.  PMF_SUPPRESS  Specifies whether to continue playing the metafile after
  13458.  resetting the presentation space. It can be one of the following values:
  13459.  
  13460.  Value                             Meaning
  13461.  ────────────────────────────────────────────────────────────────────────────
  13462.  
  13463.  SUP_DEFAULT                       Default; same as SUP_NOSUPPRESS.
  13464.  
  13465.  SUP_NOSUPPRESS                    Does not suppress the metafile.
  13466.  
  13467.  SUP_SUPPRESS                      Suppresses the metafile after the
  13468.                                    presentation space is reset as specified
  13469.                                    by the PMF_RESET option. All other
  13470.                                    options are ignored.
  13471.  
  13472.  
  13473.  
  13474.  PMF_COLORTABLES  Specifies whether to use logical color tables from the
  13475.  metafile or from the application. It can be one of the following values:
  13476.  
  13477.  Value                             Meaning
  13478.  ────────────────────────────────────────────────────────────────────────────
  13479.  
  13480.  CTAB_DEFAULT                      Default; same as CTAB_NOMODIFY.
  13481.  
  13482.  CTAB_NOMODIFY                     Uses the logical color table defined by
  13483.                                    the application. This is the default.
  13484.  
  13485.  CTAB_REPLACE                      Uses the logical color tables implied by
  13486.                                    or given in the metafile. The
  13487.                                    application's existing logical color
  13488.                                    table is overwritten.
  13489.  
  13490.  
  13491.  
  13492.  PMF_COLORREALIZABLE  Specifies whether the logical color tables defined by
  13493.  the metafile should be realizable. It can be one of the following values:
  13494.  
  13495.  Value                             Meaning
  13496.  ────────────────────────────────────────────────────────────────────────────
  13497.  
  13498.  CREA_DEFAULT                      Default; same as CREA_NOREALIZE.
  13499.  
  13500.  CREA_REALIZE                      Creates realizable color tables.
  13501.  
  13502.  CREA_NOREALIZE                    Does not create realizable color tables.
  13503.                                    This is the default.
  13504.  
  13505.  
  13506.  
  13507.  PMF_PATHBASE  Specifies a reserved element. It must be zero.
  13508.  
  13509.  PMF_RESOLVEPATH  Specifies a reserved element. It must be RSP_DEFAULT or
  13510.  RSP_NODISCARD.
  13511.  
  13512.  
  13513.  Example
  13514.  
  13515.  This example uses the GpiPlayMetaFile function to play the given metafile.
  13516.  The function uses all the default actions for playing the metafile.
  13517.  
  13518.  HMF hmf;
  13519.  LONG cSegments;
  13520.  CHAR szBuffer[80];
  13521.  
  13522.  hmf = GpiLoadMetaFile(hab, "sample.met");
  13523.  GpiPlayMetaFile(hps, hmf, 0L, (PLONG) NULL, &cSegments, 80L, szBuffer);
  13524.  
  13525.  
  13526.  
  13527.  
  13528.  
  13529.  See Also
  13530.  
  13531.  DevCloseDC, DevOpenDC, GpiCreateLogColorTable, GpiCreateLogFont,
  13532.  GpiLoadMetaFile, GpiResetPS, GpiSetDrawingMode, GpiSetViewingTransformMatrix
  13533.  
  13534.  
  13535.  
  13536.  Corrections
  13537.  
  13538.  The default value for PMF_COLORREALIZABLE is CREA_NOREALIZE, not
  13539.  CREA_REALIZE.
  13540.  
  13541.  
  13542.  █    GpiPolyLine
  13543.  ────────────────────────────────────────────────────────────────────────────
  13544.  
  13545.  LONG GpiPolyLine  (hps, cptl, aptl)
  13546.  
  13547.  HPS  hps;                         /*presentation-space handle */
  13548.  
  13549.  LONG  cptl;                       /*number of points in array */
  13550.  
  13551.  PPOINTL  aptl;                    /*address of array of structures for
  13552.                                    points */
  13553.  
  13554.  
  13555.  The GpiPolyLine function draws one or more straight lines. The function
  13556.  draws the lines by using the points specified by the aptl parameter. The
  13557.  function needs at least one point to draw a line. If a point is specified,
  13558.  the function draws the line from the current position to the point. For each
  13559.  additional line, the function needs exactly one more point, and uses the end
  13560.  point of the last line as the starting point for the next. The function
  13561.  draws the lines by using the current values of the line-color, line-mix,
  13562.  line-width, and line-type attributes.
  13563.  
  13564.  The GpiPolyLine function moves the current position to the end point of the
  13565.  last line.
  13566.  
  13567.  
  13568.  Parameters
  13569.  
  13570.  hps  Identifies a presentation space.
  13571.  
  13572.  cptl  Specifies the number of points. This parameter must be greater than or
  13573.  equal to zero.
  13574.  
  13575.  aptl  Points to an array of POINTL structures that contains the points. The
  13576.  POINTL structure has the following form:
  13577.  
  13578.  typedef struct _POINTL {
  13579.      LONG  x;
  13580.      LONG  y;
  13581.  } POINTL;
  13582.  
  13583.  
  13584.  
  13585.  
  13586.  For a full description, see Chapter 4, "Types, Macros, Structures."
  13587.  
  13588.  
  13589.  Return Value
  13590.  
  13591.  The return value is GPI_OK or GPI_HITS if the function is successful (it is
  13592.  GPI_HITS if the detectable attribute is set for the presentation space and a
  13593.  correlation hit occurs). The return value is GPI_ERROR if an error occurs.
  13594.  
  13595.  
  13596.  Errors
  13597.  
  13598.  Use the WinGetLastError function to retrieve the error value, which may be
  13599.  one of the following:
  13600.  
  13601.       PMERR_INV_COORDINATE
  13602.       PMERR_INV_HPS
  13603.       PMERR_INV_LENGTH_OR_COUNT
  13604.       PMERR_PS_BUSY
  13605.  
  13606.  
  13607.  
  13608.  
  13609.  
  13610.  Example
  13611.  
  13612.  This example uses the GpiPolyLine function to draw a triangle.
  13613.  
  13614.  POINTL ptlTriangle[] = { 100, 100, 200, 0, 0, 0 };
  13615.  
  13616.  GpiMove(hps, &ptlTriangle[2]);          /* moves to end point (0, 0) */
  13617.  GpiPolyLine(hps, 3L, &ptlTriangle[1]);  /* draws triangle            */
  13618.  
  13619.  
  13620.  
  13621.  
  13622.  
  13623.  See Also
  13624.  
  13625.  GpiLine, GpiMove, GpiSetAttrs, GpiSetColor, GpiSetCurrentPosition,
  13626.  GpiSetLineType
  13627.  
  13628.  
  13629.  Corrections
  13630.  
  13631.  The example did not draw a triangle because the starting point for
  13632.  GpiPolyLine was the same point as that moved to in the GpiMove function. The
  13633.  GpiPolyLine function was also missing a parameter.
  13634.  
  13635.  
  13636.  █    GpiQueryBitmapBits
  13637.  ────────────────────────────────────────────────────────────────────────────
  13638.  
  13639.  LONG GpiQueryBitmapBits  (hps, lScanStart, cScan, pbBuffer, pbmi)
  13640.  
  13641.  HPS  hps;                         /*presentation-space handle */
  13642.  
  13643.  LONG  lScanStart;                 /*number for first scan line to retrieve
  13644.                                    */
  13645.  
  13646.  LONG  cScan;                      /*number of scan lines to retrieve */
  13647.  
  13648.  PBYTE  pbBuffer;                  /*address of buffer for bitmap image
  13649.                                    data */
  13650.  
  13651.  PBITMAPINFO  pbmi;                /*address of structure for bitmap info
  13652.                                    */
  13653.  
  13654.  
  13655.  The GpiQueryBitmapBits function copies image data from a bitmap to the
  13656.  buffer pointed to by the pbBuffer parameter. The function copies the image
  13657.  data from the bitmap currently set for the presentation space. The
  13658.  presentation space must be associated with a memory device context.
  13659.  
  13660.  To copy the image data, the function needs the count of planes and adjacent
  13661.  color bits specified in the fields of the structure pointed to by the pbmi
  13662.  parameter. That is, the cPlanes and cBitCount fields must be set before you
  13663.  call the function. Also, the cbFix field must be set to 12. The function
  13664.  then copies the image data to the buffer. The buffer must have sufficient
  13665.  space to hold all the bytes of image data being copied. The number of bytes
  13666.  for the buffer is equal to the number of scan lines to copy, multiplied by
  13667.  the width of the bitmap in bytes (rounded up to the next multiple of 4),
  13668.  multiplied by the number of color planes. The width has to be a multiple of
  13669.  4, since the function rounds the length of each scan line to a multiple of 4
  13670.  bytes before copying. Also, the width must be multiplied by the number of
  13671.  adjacent color bits before rounding.
  13672.  
  13673.  After copying the image data, the GpiQueryBitmapBits function fills the
  13674.  remaining fields in the structure pointed to by pbmi. These fields are the
  13675.  width and height of the bitmap and the array of RGB color values for the
  13676.  bitmap pels. An application must make sure there is sufficient space in the
  13677.  structure to receive all elements of the array of RGB color values. The
  13678.  number of elements in the array depends on the format of the bitmap.
  13679.  
  13680.  
  13681.  Parameters
  13682.  
  13683.  hps  Identifies the presentation space.
  13684.  
  13685.  lScanStart  Specifies the number of the first scan line to copy to the
  13686.  buffer. If this parameter is zero, the function copies the first scan line
  13687.  in the bitmap.
  13688.  
  13689.  cScan  Specifies the number of scan lines to copy.
  13690.  
  13691.  pbBuffer  Points to the buffer that receives the bitmap image data. It must
  13692.  be large enough to hold all the bytes of the image data, from the scan line
  13693.  specified by the lScanStart parameter to the end of the bitmap.
  13694.  
  13695.  pbmi  Points to the BITMAPINFO structure that receives the bitmap
  13696.  information table. The BITMAPINFO structure has the following form:
  13697.  
  13698.  typedef struct _BITMAPINFO {
  13699.      ULONG  cbFix;
  13700.      USHORT cx;
  13701.      USHORT cy;
  13702.      USHORT cPlanes;
  13703.      USHORT cBitCount;
  13704.      RGB    argbColor[1];
  13705.  } BITMAPINFO;
  13706.  
  13707.  
  13708.  
  13709.  
  13710.  Depending on the format of the given bitmap, an application may need to
  13711.  allocate extra bytes for the structure to hold the additional elements for
  13712.  the argbColor field.
  13713.  
  13714.  For a full description, see Chapter 4, "Types, Macros, Structures."
  13715.  
  13716.  
  13717.  Return Value
  13718.  
  13719.  The return value is the number of scan lines retrieved if the function is
  13720.  successful or BMB_ERROR if an error occurred.
  13721.  
  13722.  
  13723.  Errors
  13724.  
  13725.  Use the WinGetLastError function to retrieve the error value, which may be
  13726.  one of the following:
  13727.  
  13728.       PMERR_INCORRECT_DC_TYPE
  13729.       PMERR_INV_DC_TYPE
  13730.       PMERR_INV_HPS
  13731.       PMERR_INV_INFO_TABLE
  13732.       PMERR_INV_LENGTH_OR_COUNT
  13733.       PMERR_INV_SCAN_START
  13734.       PMERR_NO_BITMAP_SELECTED
  13735.       PMERR_PS_BUSY
  13736.  
  13737.  
  13738.  
  13739.  
  13740.  
  13741.  Comments
  13742.  
  13743.  If the requested color format is not the same as the bitmap's color format,
  13744.  the function converts the bitmap image data to the requested format.
  13745.  
  13746.  For any scan line, the bits for the pixels are tightly packed, with the bits
  13747.  for the first pixel stored in the most significant bits of the first byte.
  13748.  If necessary, a scan line is padded at the end so that each scan line begins
  13749.  on a 32-bit boundary.
  13750.  
  13751.  
  13752.  Example
  13753.  
  13754.  This example uses GpiQueryBitmapBits to copy the image data of a bitmap from
  13755.  a presentation space associated with a memory device context.
  13756.  
  13757.  BITMAPINFOHEADER bmp = { 12, 640, 350, 1, 1 };
  13758.  LONG cbBuffer, cbBitmapInfo;
  13759.  SEL selBuffer, selBitmapInfo;
  13760.  PBYTE pbBuffer;
  13761.  PBITMAPINFO pbmi;
  13762.  
  13763.  /*
  13764.   * Compute the size of the image-data buffer and the bitmap
  13765.   * information structure.
  13766.   */
  13767.  
  13768.  cbBuffer = (((bmp.cBitCount * bmp.cx) + 31) / 32)
  13769.      * 4 * bmp.cy * bmp.cPlanes;
  13770.  cbBitmapInfo = sizeof(BITMAPINFO) +
  13771.      (sizeof(RGB) * (1 < bmp.cBitCount));
  13772.  
  13773.  /*
  13774.   * Allocate memory for the image data-buffer and the bitmap
  13775.   * information structure.
  13776.   */
  13777.  
  13778.  DosAllocSeg(cbBuffer, &selBuffer, SEG_NONSHARED);
  13779.  pbBuffer = MAKEP(selBuffer, 0);
  13780.  DosAllocSeg(cbBitmapInfo, &selBitmapInfo, SEG_NONSHARED);
  13781.  pbmi = MAKEP(selBitmapInfo, 0);
  13782.  
  13783.  /* Copy the image data. */
  13784.  
  13785.  pbmi->cbFix = 12;
  13786.  pbmi->cPlanes = 1;
  13787.  pbmi->cBitCount = 1;
  13788.  GpiQueryBitmapBits(hps, 0L, (LONG) bmp.cy, pbBuffer, pbmi);
  13789.  
  13790.  
  13791.  
  13792.  
  13793.  
  13794.  See Also
  13795.  
  13796.  GpiLoadBitmap, GpiQueryBitmapParameters, GpiSetBitmapBits
  13797.  
  13798.  
  13799.  Corrections
  13800.  
  13801.  The first bits in a scan line are stored in the most significant bits of the
  13802.  first byte of the scan line.
  13803.  
  13804.  
  13805.  █    GpiQueryCharDirection
  13806.  ────────────────────────────────────────────────────────────────────────────
  13807.  
  13808.  LONG GpiQueryCharDirection  (hps)
  13809.  
  13810.  HPS  hps;                         /*presentation-space handle */
  13811.  
  13812.  
  13813.  The GpiQueryCharDirection function retrieves the current value of the
  13814.  character-direction attribute. This function cannot be used in an open
  13815.  segment when the drawing mode is DM_RETAIN.
  13816.  
  13817.  
  13818.  Parameters
  13819.  
  13820.  hps  Identifies the presentation space.
  13821.  
  13822.  
  13823.  Return Value
  13824.  
  13825.  The return value is the current character-direction attribute if the
  13826.  function is successful, or CHDIRN_ERROR if an error occurs.
  13827.  
  13828.  
  13829.  Errors
  13830.  
  13831.  Use the WinGetLastError function to retrieve the error value, which may be
  13832.  one of the following:
  13833.  
  13834.       PMERR_INV_HPS
  13835.       PMERR_INV_IN_RETAIN_MODE
  13836.       PMERR_PS_BUSY
  13837.  
  13838.  
  13839.  
  13840.  
  13841.  
  13842.  Comments
  13843.  
  13844.  In MS OS/2 versions 1.2 and later, the following character directions are
  13845.  available:
  13846.  
  13847.  Value                             Meaning
  13848.  ────────────────────────────────────────────────────────────────────────────
  13849.  
  13850.  CHDIRN_LEFTRIGHT                  Left to right
  13851.  
  13852.  CHDIRN_RIGHTLEFT                  Right to left
  13853.  
  13854.  CHDIRN_TOPBOTTOM                  Top to bottom
  13855.  
  13856.  CHDIRN_BOTTOMTOP                  Bottom to top
  13857.  
  13858.  
  13859.  
  13860.  See Also
  13861.  
  13862.  GpiSetCharDirection, GpiSetDrawingMode
  13863.  
  13864.  
  13865.  Changes
  13866.  
  13867.  Character directions other than the default are allowed.
  13868.  
  13869.  
  13870.  █    GpiQueryCharStringPos
  13871.  ────────────────────────────────────────────────────────────────────────────
  13872.  
  13873.  BOOL GpiQueryCharStringPos  (hps, flOptions, cchString, pchString, adx,
  13874.  aptl)
  13875.  
  13876.  HPS  hps;                         /*presentation-space handle */
  13877.  
  13878.  ULONG  flOptions;                 /*option flags */
  13879.  
  13880.  LONG  cchString;                  /*length of the string */
  13881.  
  13882.  PCH  pchString;                   /*address of string to examine */
  13883.  
  13884.  PLONG  adx;                       /*address of array for increment values
  13885.                                    */
  13886.  
  13887.  PPOINTL  aptl;                    /*address of array of structures for
  13888.                                    points */
  13889.  
  13890.  
  13891.  The GpiQueryCharStringPos function determines a position for each character
  13892.  in the string pointed to by the pchString parameter. Each position is the
  13893.  position of the character in world coordinates as if it were drawn by using
  13894.  the GpiCharStringPos function.
  13895.  
  13896.  The GpiQueryCharStringPos function copies the character positions to the
  13897.  array of structures pointed to by the aptl parameter. It uses the current
  13898.  character attributes or the array of vector increments specified by the adx
  13899.  parameter to determine the positions. The function cannot be used in an open
  13900.  segment when the drawing mode is DM_RETAIN.
  13901.  
  13902.  
  13903.  Parameters
  13904.  
  13905.  hps  Identifies the presentation space.
  13906.  
  13907.  flOptions  Specifies whether to use the vector increments specified by the
  13908.  adx parameter. It can be one of the following values:
  13909.  
  13910.  Value                             Meaning
  13911.  ────────────────────────────────────────────────────────────────────────────
  13912.  
  13913.  0                                 Advances the current position after each
  13914.                                    character by using the width of the
  13915.                                    character. The adx parameter is ignored.
  13916.  
  13917.  CHS_VECTOR                        Advances the current position after each
  13918.                                    character by using the next value in the
  13919.                                    array adx. The current character
  13920.                                    direction defines the direction in which
  13921.                                    the current position is advanced.
  13922.  
  13923.  
  13924.  
  13925.  cchString  Specifies the length of the string pointed to by the pchString
  13926.  parameter.
  13927.  
  13928.  pchString  Points to the character string to examine.
  13929.  
  13930.  adx  Points to an array of increment values. Each value is a 4-byte signed
  13931.  integer specifying the distance (in world coordinates) to advance the
  13932.  current position for each character. There must be one value for each
  13933.  character in the string. The first element specifies the distance for the
  13934.  first character, the second element for the second character, and so on.
  13935.  This parameter may be NULL if the flOptions parameter is set to zero.
  13936.  
  13937.  aptl  Points to the array of POINTL structures that receives the position
  13938.  (in world coordinates) of each character in the string. The array must be
  13939.  large enough for each character in the string, plus one final point that
  13940.  contains the position of the first character that follows the string. The
  13941.  POINTL structure has the following form:
  13942.  
  13943.  typedef struct _POINTL  {
  13944.      LONG  x;
  13945.      LONG  y;
  13946.  } POINTL;
  13947.  
  13948.  
  13949.  
  13950.  
  13951.  For a full description, see Chapter 4, "Types, Macros, Structures."
  13952.  
  13953.  
  13954.  Return Value
  13955.  
  13956.  The return value is GPI_OK if the function is successful or GPI_ERROR if an
  13957.  error occurred.
  13958.  
  13959.  
  13960.  Errors
  13961.  
  13962.  Use the WinGetLastError function to retrieve the error value, which may be
  13963.  one of the following:
  13964.  
  13965.       PMERR_INV_CHAR_POS_OPTIONS
  13966.       PMERR_INV_COORDINATE
  13967.       PMERR_INV_HPS
  13968.       PMERR_INV_IN_RETAIN_MODE
  13969.       PMERR_INV_LENGTH_OR_COUNT
  13970.       PMERR_INV_RECT
  13971.       PMERR_PS_BUSY
  13972.  
  13973.  
  13974.  
  13975.  
  13976.  
  13977.  Example
  13978.  
  13979.  This example calls the GpiQueryCharStringPos function to determine the
  13980.  location of each character in the string. Vector increments are not used.
  13981.  
  13982.  CHAR szString[] = "Sample string";
  13983.  POINTL aptl[sizeof(szString) + 1];
  13984.  
  13985.  GpiQueryCharStringPos(hps,     /* presentation-space handle      */
  13986.      0L,                        /* does not use vector increments */
  13987.      sizeof(szString),          /* number of characters in string */
  13988.      szString,                  /* character string               */
  13989.      (PLONG) NULL,              /* no vector increments           */
  13990.      aptl);                     /* array of structures for points */
  13991.  
  13992.  
  13993.  
  13994.  
  13995.  
  13996.  See Also
  13997.  
  13998.  GpiCharStringPos, GpiQueryCharStringPosAt, GpiSetDrawingMode
  13999.  
  14000.  
  14001.  Corrections
  14002.  
  14003.  The array of points specified in the aptl parameter must include not only a
  14004.  POINTL structure for each character in the string, but also one additional
  14005.  POINTL structure that will receive the position of the first character that
  14006.  follows the string.
  14007.  
  14008.  
  14009.  █    GpiQueryCharStringPosAt
  14010.  ────────────────────────────────────────────────────────────────────────────
  14011.  
  14012.  BOOL GpiQueryCharStringPosAt  (hps, pptlStart, flOptions, cchString,
  14013.  pchString, adx, aptl)
  14014.  
  14015.  HPS  hps;                         /*presentation-space handle */
  14016.  
  14017.  PPOINTL  pptlStart;               /*address of structure for starting
  14018.                                    point */
  14019.  
  14020.  ULONG  flOptions;                 /*option flag */
  14021.  
  14022.  LONG  cchString;                  /*length of the string */
  14023.  
  14024.  PCH  pchString;                   /*address of string to examine */
  14025.  
  14026.  PLONG  adx;                       /*address of array for increment values
  14027.                                    */
  14028.  
  14029.  PPOINTL  aptl;                    /*address of array of structures for
  14030.                                    points */
  14031.  
  14032.  
  14033.  The GpiQueryCharStringPosAt function determines a position for each
  14034.  character in the character string pointed to by the pchString parameter. The
  14035.  positions are determined as if the application had called the
  14036.  GpiCharStringPosAt function and are specified in world coordinates.
  14037.  
  14038.  The GpiQueryCharStringPosAt function copies the character positions to the
  14039.  array of structures pointed to by the aptl parameter. It uses the current
  14040.  character attributes or the array of vector increments specified by the adx
  14041.  parameter to determine the positions. The function cannot be used in an open
  14042.  segment when the drawing mode is DM_RETAIN.
  14043.  
  14044.  
  14045.  Parameters
  14046.  
  14047.  hps  Identifies the presentation space.
  14048.  
  14049.  pptlStart  Points to the POINTL structure that specifies the starting point
  14050.  (in world coordinates) of the character string. The POINTL structure has the
  14051.  following form:
  14052.  
  14053.  typedef struct _POINTL {
  14054.      LONG  x;
  14055.      LONG  y;
  14056.  } POINTL;
  14057.  
  14058.  
  14059.  
  14060.  
  14061.  For a full description, see Chapter 4, "Types, Macros, Structures."
  14062.  
  14063.  flOptions  Specifies whether to use the vector increments specified by the
  14064.  adx parameter. It can be one of the following values:
  14065.  
  14066.  Value                             Meaning
  14067.  ────────────────────────────────────────────────────────────────────────────
  14068.  
  14069.  0                                 Advances the current position after each
  14070.                                    character by using the width of the
  14071.                                    character. The adx parameter is ignored.
  14072.  
  14073.  CHS_VECTOR                        Advances the current position after each
  14074.                                    character by using the next value in the
  14075.                                    array adx. The current character
  14076.                                    direction defines the direction in which
  14077.                                    the current position is advanced.
  14078.  
  14079.  
  14080.  
  14081.  cchString  Specifies the length (in bytes) of the string pointed to by the
  14082.  pchString parameter.
  14083.  
  14084.  pchString  Points to the character string to examine.
  14085.  
  14086.  adx  Points to an array of increment values. Each value is a 4-byte signed
  14087.  integer specifying the distance (in world coordinates) to advance the
  14088.  current position for each character. There must be one value for each
  14089.  character in the string. The first element specifies the distance for the
  14090.  first character, the second element for the second character, and so on.
  14091.  
  14092.  aptl  Points to the array of POINTL structures that receives the position
  14093.  (in world coordinates) of each character in the string, including the
  14094.  terminating null character.
  14095.  
  14096.  
  14097.  Return Value
  14098.  
  14099.  The return value is GPI_OK if the function is successful or GPI_ERROR if an
  14100.  error occurred.
  14101.  
  14102.  
  14103.  Errors
  14104.  
  14105.  Use the WinGetLastError function to retrieve the error value, which may be
  14106.  one of the following:
  14107.  
  14108.       PMERR_INV_CHAR_POS_OPTIONS
  14109.       PMERR_INV_COORDINATE
  14110.       PMERR_INV_HPS
  14111.       PMERR_INV_IN_RETAIN_MODE
  14112.       PMERR_INV_LENGTH_OR_COUNT
  14113.       PMERR_INV_RECT
  14114.       PMERR_PS_BUSY
  14115.  
  14116.  
  14117.  
  14118.  
  14119.  
  14120.  Example
  14121.  
  14122.  This example uses the GpiQueryCharStringPosAt function to determine the
  14123.  location of each character in the string. Vector increments are not used.
  14124.  
  14125.  POINTL ptlStart = { 100, 100 };
  14126.  POINTL aptl[12];
  14127.  
  14128.  GpiQueryCharStringPosAt(hps,  /* presentation-space handle                */
  14129.      &ptlStart,                /* starting point for string                */
  14130.      0L,                       /* do not use vector increments             */
  14131.      12L,                      /* length of string + terminating null char */
  14132.      "This string",            /* character string                         */
  14133.      (PLONG) NULL,             /* no vector increments                     */
  14134.      aptl);                    /* array of structures for points           */
  14135.  
  14136.  
  14137.  
  14138.  
  14139.  
  14140.  See Also
  14141.  
  14142.  GpiCharStringPosAt, GpiQueryCharStringPos, GpiSetDrawingMode
  14143.  
  14144.  
  14145.  Corrections
  14146.  
  14147.  The array of POINTL structures specified in the aptl parameter must be large
  14148.  enough to include the terminating null character at the end of the string.
  14149.  
  14150.  
  14151.  █    GpiQueryDefArcParams
  14152.  ────────────────────────────────────────────────────────────────────────────
  14153.  
  14154.  BOOL GpiQueryDefArcParams  (hps, parcp)
  14155.  
  14156.  HPS  hps;                         /*presentation-space handle */
  14157.  
  14158.  PARCPARAMS  parcp;                /*pointer to structure for arc
  14159.                                    parameters */
  14160.  
  14161.  
  14162.  The GpiQueryDefArcParams function retrieves the default arc parameters. The
  14163.  default arc parameters define the values given to the arc parameters of a
  14164.  presentation space whenever that presentation space is reset. (The arc
  14165.  parameters define the shape and orientation of the ellipses drawn using the
  14166.  arc functions.) A presentation space can be reset by using the GpiResetPS
  14167.  function.
  14168.  
  14169.  
  14170.  Parameters
  14171.  
  14172.  hps  Identifies the presentation space.
  14173.  
  14174.  parcp  Points to the ARCPARAMS structure that receives the arc parameters.
  14175.  The ARCPARAMS structure has the following form:
  14176.  
  14177.  typedef struct _ARCPARAMS {
  14178.      LONG lP;
  14179.      LONG lQ;
  14180.      LONG lR;
  14181.      LONG lS;
  14182.  } ARCPARAMS;
  14183.  
  14184.  
  14185.  
  14186.  
  14187.  For a full description, see Chapter 4, "Types, Macros, Structures."
  14188.  
  14189.  
  14190.  Return Value
  14191.  
  14192.  
  14193.  
  14194.  The return value is GPI_OK if the function is successful or GPI_ERROR if an
  14195.  error occurs.
  14196.  
  14197.  
  14198.  Errors
  14199.  
  14200.  Use the WinGetLastError function to retrieve the error value, which may be
  14201.  one of the following:
  14202.  
  14203.       PMERR_INV_COORDINATE
  14204.       PMERR_INV_HPS
  14205.       PMERR_PS_BUSY
  14206.  
  14207.  
  14208.  
  14209.  
  14210.  
  14211.  See Also
  14212.  
  14213.  GpiQueryArcParams, GpiSetDefArcParams
  14214.  
  14215.  
  14216.  █    GpiQueryDefAttrs
  14217.  ────────────────────────────────────────────────────────────────────────────
  14218.  
  14219.  BOOL GpiQueryDefAttrs  (hps, lPrimType, flAttrMask, pbunAttrs)
  14220.  
  14221.  HPS  hps;                         /*presentation-space handle */
  14222.  
  14223.  LONG  lPrimType;                  /*primitive type */
  14224.  
  14225.  ULONG  flAttrMask;                /*attributes mask */
  14226.  
  14227.  PBUNDLE  pbunAttrs;               /*pointer to structure for default
  14228.                                    attributes */
  14229.  
  14230.  
  14231.  The GpiQueryDefAttrs function retrieves the default attributes for a
  14232.  primitive. The default attributes define the values given to a presentation
  14233.  space's attributes when that presentation space is reset. The default
  14234.  attributes also define the value of attributes when they are explicitly set
  14235.  to the default by using the GpiSetAttrs function.
  14236.  
  14237.  
  14238.  Parameters
  14239.  
  14240.  hps  Identifies the presentation space.
  14241.  
  14242.  lPrimType  Specifies which primitive type to retrieve attributes for. It can
  14243.  be one of the following values:
  14244.  
  14245.  Value                             Meaning
  14246.  ────────────────────────────────────────────────────────────────────────────
  14247.  
  14248.  PRIM_AREA                         Area primitives
  14249.  
  14250.  PRIM_CHAR                         Character primitives
  14251.  
  14252.  PRIM_IMAGE                        Image primitives
  14253.  
  14254.  PRIM_LINE                         Line and arc primitives
  14255.  
  14256.  PRIM_MARKER                       Marker primitives
  14257.  
  14258.  
  14259.  
  14260.  flAttrMask  Specifies which attributes to retrieve. The values for this
  14261.  parameter depend on the primitive type specified by the lPrimType parameter.
  14262.  This parameter can be any combination of the following values for a specific
  14263.  type:
  14264.  
  14265.  Type                              Values
  14266.  ────────────────────────────────────────────────────────────────────────────
  14267.  
  14268.  PRIM_AREA                         ABB_COLOR, ABB_BACK_COLOR, ABB_MIX_MODE,
  14269.                                    ABB_BACK_MIX_MODE, ABB_SET, ABB_SYMBOL,
  14270.                                    ABB_REF_POINT
  14271.  
  14272.  PRIM_CHAR                         CBB_COLOR, CBB_BACK_COLOR, CBB_MIX_MODE,
  14273.                                    CBB_BACK_MIX_MODE, CBB_SET, CBB_MODE,
  14274.                                    CBB_BOX, CBB_ANGLE, CBB_SHEAR,
  14275.                                    CBB_DIRECTION
  14276.  
  14277.  PRIM_IMAGE                        IBB_COLOR, IBB_BACK_COLOR, IBB_MIX_MODE,
  14278.                                    IBB_BACK_MIX_MODE
  14279.  
  14280.  PRIM_LINE                         LBB_COLOR, LBB_MIX_MODE, LBB_WIDTH,
  14281.                                    LBB_GEOM_WIDTH, LBB_TYPE, LBB_END,
  14282.                                    LBB_JOIN
  14283.  
  14284.  PRIM_MARKER                       MBB_COLOR, MBB_BACK_COLOR, MBB_MIX_MODE,
  14285.                                    MBB_BACK_MIX_MODE, MBB_SET, MBB_SYMBOL,
  14286.                                    MBB_BOX
  14287.  
  14288.  
  14289.  
  14290.  If this parameter is zero, the function does not retrieve attributes but
  14291.  still returns a mask that specifies the attributes using default values.
  14292.  
  14293.  pbunAttrs  Points to the structure that receives the default attribute
  14294.  values for each attribute specified by the flAttrMask parameter. The type of
  14295.  structure depends on the value of the lPrimType parameter; it can be one of
  14296.  following structures:
  14297.  
  14298.  Type                              Structure
  14299.  ────────────────────────────────────────────────────────────────────────────
  14300.  
  14301.  PRIM_AREA                         AREABUNDLE
  14302.  
  14303.  PRIM_CHAR                         CHARBUNDLE
  14304.  
  14305.  PRIM_IMAGE                        IMAGEBUNDLE
  14306.  
  14307.  PRIM_LINE                         LINEBUNDLE
  14308.  
  14309.  PRIM_MARKER                       MARKERBUNDLE
  14310.  
  14311.  
  14312.  
  14313.  Return Value
  14314.  
  14315.  The return value is GPI_OK if the function is successful or GPI_ERROR if an
  14316.  error occurs.
  14317.  
  14318.  
  14319.  Errors
  14320.  
  14321.  Use the WinGetLastError function to retrieve the error value, which may be
  14322.  one of the following:
  14323.  
  14324.      PMERR_HUGE_FONTS_NOT_SUPPORTED
  14325.      PMERR_INV_BACKGROUND_COL_ATTR
  14326.      PMERR_INV_CHAR_ANGLE_ATTR
  14327.      PMERR_INV_CHAR_DIRECTION_ATTR
  14328.      PMERR_INV_CHAR_MODE_ATTR
  14329.      PMERR_INV_CHAR_SET_ATTR
  14330.      PMERR_INV_CHAR_SHEAR_ATTR
  14331.      PMERR_INV_COLOR_ATTR
  14332.      PMERR_INV_COORDINATE
  14333.      PMERR_INV_GEOM_LINE_WIDTH_ATTR
  14334.      PMERR_INV_HPS
  14335.      PMERR_INV_LINE_END_ATTR
  14336.      PMERR_INV_LINE_JOIN_ATTR
  14337.      PMERR_INV_LINE_TYPE_ATTR
  14338.      PMERR_INV_LINE_WIDTH_ATTR
  14339.      PMERR_INV_MARKER_SET_ATTR
  14340.      PMERR_INV_MARKER_SYMBOL_ATTR
  14341.      PMERR_INV_MIX_ATTR
  14342.      PMERR_INV_PATTERN_ATTR
  14343.      PMERR_INV_PATTERN_SET_ATTR
  14344.      PMERR_INV_PATTERN_SET_FONT
  14345.      PMERR_INV_PRIMITIVE_TYPE
  14346.      PMERR_PS_BUSY
  14347.      PMERR_UNSUPPORTED_ATTR
  14348.      PMERR_UNSUPPORTED_ATTR_VALUE
  14349.  
  14350.  
  14351.  
  14352.  
  14353.  
  14354.  See Also
  14355.  
  14356.  GpiQueryAttrs, GpiSetDefAttrs
  14357.  
  14358.  
  14359.  █    GpiQueryDefTag
  14360.  ────────────────────────────────────────────────────────────────────────────
  14361.  
  14362.  BOOL GpiQueryDefTag  (hps, plTag)
  14363.  
  14364.  HPS  hps;                         /*presentation-space handle */
  14365.  
  14366.  PLONG  plTag;                     /*pointer to tag */
  14367.  
  14368.  
  14369.  The GpiQueryDefTag function retrieves the default primitive tag. A primitive
  14370.  tag is a way to identify a primitive stored in a segment.
  14371.  
  14372.  
  14373.  Parameters
  14374.  
  14375.  hps  Identifies the presentation space.
  14376.  
  14377.  plTag  Points to the variable that receives the tag.
  14378.  
  14379.  
  14380.  Return Value
  14381.  
  14382.  The return value is GPI_OK if the function is successful or GPI_ERROR if an
  14383.  error occurs.
  14384.  
  14385.  
  14386.  Errors
  14387.  
  14388.  Use the WinGetLastError function to retrieve the error value, which may be
  14389.  one of the following:
  14390.  
  14391.       PMERR_INV_HPS
  14392.       PMERR_INV_MICROPS_FUNCTION
  14393.       PMERR_PS_BUSY
  14394.  
  14395.  
  14396.  
  14397.  
  14398.  
  14399.  See Also
  14400.  
  14401.  GpiCorrelateChain, GpiCorrelateFrom, GpiSetDefTag
  14402.  
  14403.  
  14404.  █    GpiQueryDefViewingLimits
  14405.  ────────────────────────────────────────────────────────────────────────────
  14406.  
  14407.  BOOL GpiQueryDefViewingLimits  (hps, prclLimits)
  14408.  
  14409.  HPS  hps;                         /*presentation-space handle */
  14410.  
  14411.  PRECTL  prclLimits;               /*pointer to structure for viewing
  14412.                                    limits */
  14413.  
  14414.  
  14415.  The GpiQueryDefViewingLimits function retrieves the default viewing limits.
  14416.  The default viewing limits define the values given to a presentation space's
  14417.  viewing limits whenever that presentation space is reset. (The viewing
  14418.  limits specify a rectangle in model space that the system uses to clip
  14419.  output.) A presentation space can be reset by using the GpiResetPS function.
  14420.  
  14421.  
  14422.  
  14423.  Parameters
  14424.  
  14425.  hps  Identifies the presentation space.
  14426.  
  14427.  prclLimits  Points to the RECTL structure that receives the coordinates of
  14428.  the default viewing limits. The RECTL structure has the following form:
  14429.  
  14430.  typedef struct _RECTL {
  14431.      LONG  xLeft;
  14432.      LONG  yBottom;
  14433.      LONG  xRight;
  14434.      LONG  yTop;
  14435.  } RECTL;
  14436.  
  14437.  
  14438.  
  14439.  
  14440.  For a full description, see Chapter 4, "Types, Macros, Structures."
  14441.  
  14442.  
  14443.  Return Value
  14444.  
  14445.  The return value is GPI_OK if the function is successful or GPI_ERROR if an
  14446.  error occurs.
  14447.  
  14448.  
  14449.  Errors
  14450.  
  14451.  Use the WinGetLastError function to retrieve the error value, which may be
  14452.  one of the following:
  14453.  
  14454.       PMERR_INV_COORDINATE
  14455.       PMERR_INV_HPS
  14456.       PMERR_INV_VIEWING_LIMITS
  14457.       PMERR_PS_BUSY
  14458.  
  14459.  
  14460.  
  14461.  
  14462.  
  14463.  See Also
  14464.  
  14465.  GpiQueryViewingLimits, GpiSetDefViewingLimits
  14466.  
  14467.  
  14468.  █    GpiQueryFontFileDescriptions
  14469.  ────────────────────────────────────────────────────────────────────────────
  14470.  
  14471.  LONG GpiQueryFontFileDescriptions  (hab, pszFileName, pcFonts, pffdescs)
  14472.  
  14473.  HAB  hab;                         /*anchor-block handle */
  14474.  
  14475.  PSZ  pszFileName;                 /*address of the font-resource filename
  14476.                                    */
  14477.  
  14478.  PLONG  pcFonts;                   /*address of variable with number of
  14479.                                    fonts */
  14480.  
  14481.  PFFDESCS  pffdescs;               /*array of names */
  14482.  
  14483.  
  14484.  The GpiQueryFontFileDescriptions function retrieves the typeface family and
  14485.  names contained in the specified file if the file is a font-resource file.
  14486.  The function copies the names to the array pointed to by the pffdescs
  14487.  parameter. Each name is a null-terminated string up to 32 characters long.
  14488.  The function copies all names in the file up to the number of names
  14489.  specified by the pcFonts parameter.
  14490.  
  14491.  
  14492.  Parameters
  14493.  
  14494.  hab  Identifies the anchor block.
  14495.  
  14496.  pszFileName  Points to a null-terminated string. This string must be a valid
  14497.  MS OS/2 filename. If it does not specify a path and the .fon filename
  14498.  extension, the function appends the default extension (.dll) and looks for
  14499.  the font-resource file in the directories specified by the libpath command
  14500.  in the config.sys file.
  14501.  
  14502.  pcFonts  Points to a variable specifying the maximum number of typeface
  14503.  family and name pairs to retrieve. The function copies the actual number of
  14504.  descriptions it retrieved to this variable.
  14505.  
  14506.  pffdescs  Points to the array to receive the typeface family and names for
  14507.  each font. Each array element is itself a two-element array of type FFDESCS.
  14508.  
  14509.  
  14510.  
  14511.  Return Value
  14512.  
  14513.  The return value is the number of fonts for which details were not returned
  14514.  if the function is successful or GPI_ALTERROR if an error occurred.
  14515.  
  14516.  
  14517.  Example
  14518.  
  14519.  This example uses the GpiQueryFontFileDescriptions to retrieve the typeface
  14520.  family and names for the fonts in the helv.dll file. The function is called
  14521.  twice, once to determine the actual number of fonts in the file, and again
  14522.  to retrieve the descriptions.
  14523.  
  14524.  PFFDESCS pffdescs;
  14525.  SEL sel;
  14526.  LONG cFonts = 0;
  14527.  
  14528.  /* Retrieve a count of all fonts in the file. */
  14529.  
  14530.  cFonts = GpiQueryFontFileDescriptions(hab, "helv", &cFonts,
  14531.      (PFFDESCS) NULL);
  14532.  
  14533.  /* Allocate space for the descriptions. */
  14534.  
  14535.  DosAllocSeg((USHORT) (cFonts * sizeof(FFDESCS)), &sel, SEG_NONSHARED);
  14536.  pffdescs = MAKEP(sel, 0);
  14537.  
  14538.  /* Retrieve the descriptions. */
  14539.  
  14540.  GpiQueryFontFileDescriptions(hab, "helv", &cFonts, pffdescs);
  14541.  
  14542.  
  14543.  
  14544.  
  14545.  
  14546.  See Also
  14547.  
  14548.  GpiQueryFonts
  14549.  
  14550.  
  14551.  Corrections
  14552.  
  14553.  In the example, the function retrieves information from the helv.dll file,
  14554.  not the helv.fon file. If no path and filename extension are given, the
  14555.  function by default searches for a file that has the .dll extension. Also,
  14556.  the cFonts variable must be set to zero for the first call to the function.
  14557.  
  14558.  
  14559.  █    GpiQueryMetaFileBits
  14560.  ────────────────────────────────────────────────────────────────────────────
  14561.  
  14562.  BOOL GpiQueryMetaFileBits  (hmf, off, cbBuffer, pbBuffer)
  14563.  
  14564.  HMF  hmf;                         /*metafile handle */
  14565.  
  14566.  LONG  off;                        /*offset to the first metafile byte to
  14567.                                    copy */
  14568.  
  14569.  LONG  cbBuffer;                   /*length in bytes of buffer */
  14570.  
  14571.  PBYTE  pbBuffer;                  /*address of buffer for metafile data */
  14572.  
  14573.  
  14574.  The GpiQueryMetaFileBits function copies data from the metafile specified by
  14575.  hmf to the buffer pointed to by the pbBuffer parameter. The function copies
  14576.  the bytes of the metafile, up to the number of bytes specified by cbBuffer,
  14577.  starting at the byte whose offset from the beginning of the metafile is
  14578.  specified by the off parameter.
  14579.  
  14580.  
  14581.  Parameters
  14582.  
  14583.  hmf  Identifies the memory metafile.
  14584.  
  14585.  off  Specifies the offset in bytes from the beginning of the metafile to the
  14586.  first byte to copy.
  14587.  
  14588.  cbBuffer  Specifies the number of bytes of metafile data to copy.
  14589.  
  14590.  pbBuffer  Points to the buffer to receive the metafile data. It must have
  14591.  the number of bytes specified by the cbBuffer parameter.
  14592.  
  14593.  
  14594.  Return Value
  14595.  
  14596.  The return value is GPI_OK if the function is successful or GPI_ERROR if an
  14597.  error occurred.
  14598.  
  14599.  
  14600.  Errors
  14601.  
  14602.  Use the WinGetLastError function to retrieve the error value, which may be
  14603.  one of the following:
  14604.  
  14605.       PMERR_INV_HMF
  14606.       PMERR_INV_METAFILE_LENGTH
  14607.       PMERR_INV_METAFILE_OFFSET
  14608.  
  14609.  
  14610.  
  14611.  
  14612.  
  14613.  See Also
  14614.  
  14615.  GpiQueryMetaFileLength, GpiSetMetaFileBits
  14616.  
  14617.  
  14618.  Corrections
  14619.  
  14620.  In the example, the first parameter of the GpiQueryMetaFileBits function is
  14621.  a handle of the metafile, not a handle to the presentation space. Also, the
  14622.  metafile is assumed to be no greater than 64K. For larger metafiles, you can
  14623.  use the DosAllocHuge function to allocate segments to receive the metafile
  14624.  bits.
  14625.  
  14626.  
  14627.  █    GpiResetPS
  14628.  ────────────────────────────────────────────────────────────────────────────
  14629.  
  14630.  BOOL GpiResetPS  (hps, flOption)
  14631.  
  14632.  HPS  hps;                         /*presentation-space handle */
  14633.  
  14634.  ULONG  flOption;                  /*reset option */
  14635.  
  14636.  
  14637.  The GpiResetPS function resets the presentation space. In general, resetting
  14638.  the presentation space restores attributes to their default values─that is,
  14639.  the values given to the attributes when the presentation space was created
  14640.  or the values specified in the last call to the GpiSetDefAttrs function. The
  14641.  function can reset the presentation space in three ways: as if a segment
  14642.  were closed; as if the presentation space had just been created, but without
  14643.  deleting any resources; and as if the presentation space had just been
  14644.  created. It uses the flOption parameter to determine how to reset the
  14645.  presentation space.
  14646.  
  14647.  The GpiResetPS function does not draw or erase the device. It is up to the
  14648.  application to erase the screen, if this is required. Also, the function
  14649.  does not affect the association between the specified presentation space and
  14650.  a device context.
  14651.  
  14652.  The GpiResetPS function also deselects a bitmap if any are selected into a
  14653.  memory device context.
  14654.  
  14655.  
  14656.  Parameters
  14657.  
  14658.  hps  Identifies the presentation space.
  14659.  
  14660.  flOption  Specifies the reset option. It can be one of the following:
  14661.  
  14662.  Value                             Meaning
  14663.  ────────────────────────────────────────────────────────────────────────────
  14664.  
  14665.  GRES_ATTRS                        Sets all current attributes to their
  14666.                                    default values, the current model
  14667.                                    transform to unity, and the current
  14668.                                    position to (0,0). The option also ends
  14669.                                    any open path, area, or element brackets
  14670.                                    and closes any open segment. Finally, it
  14671.                                    sets the current clip path and viewing
  14672.                                    limits to their widest possible values.
  14673.  
  14674.  GRES_SEGMENTS                     Resets as described for GRES_ATTRS, plus
  14675.                                    it deletes all retained segments, clears
  14676.                                    any boundary data, releases the clip
  14677.                                    region (if any), enables kerning (if the
  14678.                                    device supports it), and sets the
  14679.                                    default values for initial segment
  14680.                                    attributes, default viewing transform,
  14681.                                    graphics field, drawing mode, draw
  14682.                                    controls, edit mode, and attribute mode.
  14683.  
  14684.  GRES_ALL                          Resets as described for GRES_ATTRS and
  14685.                                    GRES_SEGMENTS, plus it deletes any
  14686.                                    logical fonts and local identifiers for
  14687.                                    bitmaps and sets the logical color table
  14688.                                    to its default value.
  14689.  
  14690.  
  14691.  
  14692.  Return Value
  14693.  
  14694.  The return value is GPI_OK if the function is successful or GPI_ERROR if an
  14695.  error occurred.
  14696.  
  14697.  
  14698.  Errors
  14699.  
  14700.  Use the WinGetLastError function to retrieve the error value, which may be
  14701.  one of the following:
  14702.  
  14703.       PMERR_INV_HPS
  14704.       PMERR_INV_RESET_OPTIONS
  14705.       PMERR_PS_BUSY
  14706.  
  14707.  
  14708.  
  14709.  
  14710.  
  14711.  See Also
  14712.  
  14713.  GpiAssociate, GpiCreatePS, GpiSetAttrs
  14714.  
  14715.  
  14716.  Changes
  14717.  
  14718.  Calling GpiResetPS resets the attributes of the presentation space to the
  14719.  values it had when created or to the values specified in the last call to
  14720.  GpiSetDefAttrs.
  14721.  
  14722.  
  14723.  Corrections
  14724.  
  14725.  GpiResetPS also deselects a bitmap if any are selected into a memory device
  14726.  context.
  14727.  
  14728.  
  14729.  █    GpiRotate
  14730.  ────────────────────────────────────────────────────────────────────────────
  14731.  
  14732.  BOOL GpiRotate  (hps, pmatlf, flType, fxAngle, pptl)
  14733.  
  14734.  HPS  hps;                         /*presentation-space handle */
  14735.  
  14736.  PMATRIXLF  pmatlf;                /*pointer to structure with matrix */
  14737.  
  14738.  LONG  flType;                     /*transformation type */
  14739.  
  14740.  FIXED  fxAngle;                   /*pointer to variable with rotation
  14741.                                    angle */
  14742.  
  14743.  PPOINTL  pptl;                    /*pointer to structure with center point
  14744.                                    */
  14745.  
  14746.  
  14747.  The GpiRotate function creates a transformation that can be used to rotate
  14748.  objects around a given point. GpiRotate either adds the specified rotation
  14749.  to an existing transformation or replaces the existing transformation with
  14750.  the rotation. The new transformation can be used in a subsequent call to any
  14751.  transformation function.
  14752.  
  14753.  
  14754.  Parameters
  14755.  
  14756.  hps  Identifies the presentation space.
  14757.  
  14758.  pmatlf  Points to the MATRIXLF structure that contains the transformation
  14759.  matrix. The MATRIXLF structure has following form:
  14760.  
  14761.  typedef struct _MATRIXLF {
  14762.      FIXED fxM11;
  14763.      FIXED fxM12;
  14764.      LONG  lM13;
  14765.      FIXED fxM21;
  14766.      FIXED fxM22;
  14767.      LONG  lM23;
  14768.      LONG  lM31;
  14769.      LONG  lM32;
  14770.      LONG  lM33;
  14771.  } MATRIXLF;
  14772.  
  14773.  
  14774.  
  14775.  
  14776.  For a full description, see Chapter 4, "Types, Macros, Structures."
  14777.  
  14778.  flType  Specifies how the specified matrix should be used to modify the
  14779.  transformation. It can be one of the following values:
  14780.  
  14781.  Value                             Meaning
  14782.  ────────────────────────────────────────────────────────────────────────────
  14783.  
  14784.  TRANSFORM_ADD                     Additive. The specified transformation
  14785.                                    matrix is combined with the existing
  14786.                                    transformation, with the existing
  14787.                                    transformation first, the new
  14788.                                    transformation second. This option is
  14789.                                    useful for incremental updates to
  14790.                                    transformations.
  14791.  
  14792.  TRANSFORM_REPLACE                 New/replace. The previous transformation
  14793.                                    is discarded and replaced by the
  14794.                                    specified transformation matrix.
  14795.  
  14796.  
  14797.  
  14798.  fxAngle  Specifies the rotation (in degrees) to use.
  14799.  
  14800.  pptl  Points to the POINTL structure that contains the coordinates of a
  14801.  point, relative to the origin, that defines the center of rotation. The
  14802.  POINTL structure has the following form:
  14803.  
  14804.  typedef struct _POINTL {
  14805.      LONG  x;
  14806.      LONG  y;
  14807.  } POINTL;
  14808.  
  14809.  
  14810.  
  14811.  
  14812.  For a full description, see Chapter 4, "Types, Macros, Structures."
  14813.  
  14814.  
  14815.  Return Value
  14816.  
  14817.  The return value is GPI_OK if the function is successful or GPI_ERROR if an
  14818.  error occurs.
  14819.  
  14820.  
  14821.  Errors
  14822.  
  14823.  Use the WinGetLastError function to retrieve the error value, which may be
  14824.  the following:
  14825.  
  14826.       PMERR_INV_TRANSFORM_TYPE
  14827.  
  14828.  
  14829.  
  14830.  
  14831.  
  14832.  See Also
  14833.  
  14834.  GpiScale, GpiSetDefaultViewMatrix, GpiSetModelTransformMatrix,
  14835.  GpiSetSegmentTransformMatrix, GpiSetViewingTransformMatrix, GpiTranslate
  14836.  
  14837.  
  14838.  █    GpiScale
  14839.  ────────────────────────────────────────────────────────────────────────────
  14840.  
  14841.  BOOL GpiScale  (hps, pmatlf, flType, afxScale, pptl)
  14842.  
  14843.  HPS  hps;                         /*presentation-space handle */
  14844.  
  14845.  PMATRIXLF  pmatlf;                /*pointer to structure for matrix */
  14846.  
  14847.  LONG  flType;                     /*transformation type */
  14848.  
  14849.  PFIXED  afxScale;                 /*pointer to variable with scaling
  14850.                                    factor */
  14851.  
  14852.  PPOINTL  pptl;                    /*pointer to structure with point data
  14853.                                    */
  14854.  
  14855.  
  14856.  The GpiScale function creates a transformation that can be used to scale
  14857.  (expand or contract) an object relative to a given point. GpiScale either
  14858.  adds the specified scaling factor to an existing transformation or replaces
  14859.  the existing transformation. The new transformation can be used in a
  14860.  subsequent call to any transformation function.
  14861.  
  14862.  
  14863.  Parameters
  14864.  
  14865.  hps  Identifies the presentation space.
  14866.  
  14867.  pmatlf  Points to the MATRIXLF structure that contains the transformation
  14868.  matrix. The MATRIXLF structure has the following form:
  14869.  
  14870.  typedef struct _MATRIXLF {
  14871.      FIXED fxM11;
  14872.      FIXED fxM12;
  14873.      LONG  lM13;
  14874.      FIXED fxM21;
  14875.      FIXED fxM22;
  14876.      LONG  lM23;
  14877.      LONG  lM31;
  14878.      LONG  lM32;
  14879.      LONG  lM33;
  14880.  } MATRIXLF;
  14881.  
  14882.  
  14883.  
  14884.  
  14885.  For a full description, see Chapter 4, "Types, Macros, Structures."
  14886.  
  14887.  flType  Specifies how a specified matrix should be used to modify the
  14888.  transformation. It can be one of the following values:
  14889.  
  14890.  Value                             Meaning
  14891.  ────────────────────────────────────────────────────────────────────────────
  14892.  
  14893.  TRANSFORM_ADD                     Additive. The specified transformation
  14894.                                    matrix is combined with the existing
  14895.                                    transformation, with the existing
  14896.                                    transformation first, the new
  14897.                                    transformation second. This option is
  14898.                                    useful for incremental updates to
  14899.                                    transformations.
  14900.  
  14901.  TRANSFORM_REPLACE                 New/replace. The previous transformation
  14902.                                    is discarded and replaced by the
  14903.                                    specified transformation matrix.
  14904.  
  14905.  
  14906.  
  14907.  afxScale  Points to the two-element array that contains the scaling factors
  14908.  to use. The first element specifies the scaling factor along the x-axis; the
  14909.  second specifies the scaling factor along the y-axis.
  14910.  
  14911.  pptl  Points to the POINTL structure that contains the coordinates of the
  14912.  point, relative to the origin, that defines the center of the scale. The
  14913.  POINTL structure has the following form:
  14914.  
  14915.  typedef struct _POINTL {
  14916.      LONG  x;
  14917.      LONG  y;
  14918.  } POINTL;
  14919.  
  14920.  
  14921.  
  14922.  
  14923.  For a full description, see Chapter 4, "Types, Macros, Structures."
  14924.  
  14925.  
  14926.  Return Value
  14927.  
  14928.  The return value is GPI_OK if the function is successful or GPI_ERROR if an
  14929.  error occurs.
  14930.  
  14931.  
  14932.  Errors
  14933.  
  14934.  Use the WinGetLastError function to retrieve the error value, which may be
  14935.  the following:
  14936.  
  14937.  PMERR_INV_TRANSFORM_TYPE
  14938.  
  14939.  
  14940.  
  14941.  
  14942.  
  14943.  See Also
  14944.  
  14945.  GpiRotate, GpiSetDefaultViewMatrix, GpiSetModelTransformMatrix,
  14946.  GpiSetSegmentTransformMatrix, GpiSetViewingTransformMatrix, GpiTranslate
  14947.  
  14948.  
  14949.  █    GpiSetCharDirection
  14950.  ────────────────────────────────────────────────────────────────────────────
  14951.  
  14952.  BOOL GpiSetCharDirection  (hps, flDirection)
  14953.  
  14954.  HPS  hps;                         /*presentation-space handle */
  14955.  
  14956.  LONG  flDirection;                /*character direction */
  14957.  
  14958.  
  14959.  The GpiSetCharDirection function sets the character direction for drawing
  14960.  characters. The character direction specifies the direction to advance after
  14961.  drawing a character, relative to the baseline.
  14962.  
  14963.  If the attribute mode is AM_PRESERVE, the function saves the previous
  14964.  character direction on the attribute stack when it sets the new direction.
  14965.  The previous character direction can be retrieved by using the GpiPop
  14966.  function.
  14967.  
  14968.  
  14969.  Parameters
  14970.  
  14971.  hps  Identifies the presentation space.
  14972.  
  14973.  flDirection  Specifies the character direction. This parameter can be one of
  14974.  the following values:
  14975.  
  14976.  Value                             Meaning
  14977.  ────────────────────────────────────────────────────────────────────────────
  14978.  
  14979.  CHDIRN_DEFAULT                    Default direction (left to right)
  14980.  
  14981.  CHDIRN_LEFTRIGHT                  Left to right
  14982.  
  14983.  CHDIRN_RIGHTLEFT                  Right to left
  14984.  
  14985.  CHDIRN_TOPBOTTOM                  Top to bottom
  14986.  
  14987.  CHDIRN_BOTTOMTOP                  Bottom to top
  14988.  
  14989.  
  14990.  
  14991.  Return Value
  14992.  
  14993.  The return value is GPI_OK if the function is successful or GPI_ERROR if an
  14994.  error occurs.
  14995.  
  14996.  
  14997.  Errors
  14998.  
  14999.  Use the WinGetLastError function to retrieve the error value, which may be
  15000.  one of the following:
  15001.  
  15002.       PMERR_INV_CHAR_DIRECTION_ATTR
  15003.       PMERR_INV_HPS
  15004.       PMERR_PS_BUSY
  15005.  
  15006.  
  15007.  
  15008.  
  15009.  
  15010.  See Also
  15011.  
  15012.  GpiPop, GpiQueryCharDirection, GpiSetAttrMode, GpiSetAttrs
  15013.  
  15014.  
  15015.  Changes
  15016.  
  15017.  The following character directions can now be specified for the flDirection
  15018.  parameter:
  15019.  
  15020.  Value                             Meaning
  15021.  ────────────────────────────────────────────────────────────────────────────
  15022.  
  15023.  CHDIRN_DEFAULT                    Default direction
  15024.  
  15025.  CHDIRN_LEFTRIGHT                  Left to right
  15026.  
  15027.  CHDIRN_RIGHTLEFT                  Right to left
  15028.  
  15029.  CHDIRN_TOPBOTTOM                  Top to bottom
  15030.  
  15031.  CHDIRN_BOTTOMTOP                  Bottom to top
  15032.  
  15033.  
  15034.  
  15035.  █    GpiSetDefArcParams
  15036.  ────────────────────────────────────────────────────────────────────────────
  15037.  
  15038.  BOOL GpiSetDefArcParams  (hps, parcp)
  15039.  
  15040.  HPS  hps;                         /*presentation-space handle */
  15041.  
  15042.  PARCPARAMS  parcp;                /*pointer to structure with arc
  15043.                                    parameters */
  15044.  
  15045.  
  15046.  The GpiSetDefArcParams function sets the default arc parameters. The default
  15047.  arc parameters define the values given to the arc parameters of a
  15048.  presentation space whenever that presentation space is reset. (The arc
  15049.  parameters define the shape and orientation of the ellipses drawn using the
  15050.  arc functions.) A presentation space can be reset using the GpiResetPS
  15051.  function.
  15052.  
  15053.  
  15054.  Parameters
  15055.  
  15056.  hps  Identifies the presentation space.
  15057.  
  15058.  parcp  Points to the ARCPARAMS structure that contains the arc parameters.
  15059.  The ARCPARAMS structure has the following form:
  15060.  
  15061.  typedef struct _ARCPARAMS {
  15062.      LONG lP;
  15063.      LONG lQ;
  15064.      LONG lR;
  15065.      LONG lS;
  15066.  } ARCPARAMS;
  15067.  
  15068.  
  15069.  
  15070.  
  15071.  For a full description, see Chapter 4, "Types, Macros, Structures."
  15072.  
  15073.  
  15074.  Return Value
  15075.  
  15076.  
  15077.  
  15078.  The return value is GPI_OK if the function is successful or GPI_ERROR if an
  15079.  error occurs.
  15080.  
  15081.  
  15082.  Errors
  15083.  
  15084.  Use the WinGetLastError function to retrieve the error value, which may be
  15085.  one of the following:
  15086.  
  15087.       PMERR_INV_COORDINATE
  15088.       PMERR_INV_HPS
  15089.       PMERR_PS_BUSY
  15090.  
  15091.  
  15092.  
  15093.  
  15094.  
  15095.  Comments
  15096.  
  15097.  Setting the default arc parameters does not immediately affect the arc
  15098.  parameters. The system uses the default arc parameters only when the
  15099.  presentation space is reset. The default arc parameters are reset when the
  15100.  presentation space is reset using the GRES_SEGMENT or GRES_ALL options of
  15101.  the GpiResetPS function. The reset values for the default arc parameters are
  15102.  lP=1, lQ=1, lR=0, and lS=0.
  15103.  
  15104.  
  15105.  See Also
  15106.  
  15107.  GpiFullArc, GpiPartialArc, GpiPointArc, GpiQueryDefArcParams
  15108.  
  15109.  
  15110.  █    GpiSetDefAttrs
  15111.  ────────────────────────────────────────────────────────────────────────────
  15112.  
  15113.  BOOL GpiSetDefAttrs  (hps, lPrimType, flAttrMask, pbunAttrs)
  15114.  
  15115.  HPS  hps;                         /*presentation-space handle */
  15116.  
  15117.  LONG  lPrimType;                  /*primitive type */
  15118.  
  15119.  ULONG  flAttrMask;                /*attributes mask */
  15120.  
  15121.  PBUNDLE  pbunAttrs;               /*pointer to structure with default
  15122.                                    attributes */
  15123.  
  15124.  
  15125.  The GpiSetDefAttrs function sets the default attributes for a primitive. The
  15126.  default attributes define the values given to the attributes of a
  15127.  presentation space when that presentation space is reset. The default
  15128.  attributes also define the value of attributes when they are explicitly set
  15129.  to the default using the GpiSetAttrs function.
  15130.  
  15131.  
  15132.  Parameters
  15133.  
  15134.  hps  Identifies the presentation space.
  15135.  
  15136.  lPrimType  Specifies which primitive type to set default attributes for. It
  15137.  can be one of the following values:
  15138.  
  15139.  Value                             Meaning
  15140.  ────────────────────────────────────────────────────────────────────────────
  15141.  
  15142.  PRIM_AREA                         Area primitives
  15143.  
  15144.  PRIM_CHAR                         Character primitives
  15145.  
  15146.  PRIM_IMAGE                        Image primitives
  15147.  
  15148.  PRIM_LINE                         Line and arc primitives
  15149.  
  15150.  PRIM_MARKER                       Marker primitives
  15151.  
  15152.  
  15153.  
  15154.  flAttrMask  Specifies which default attributes to set. The values for this
  15155.  parameter depend on the primitive type specified by the lPrimType parameter.
  15156.  This parameter can be any combination of the following values for a specific
  15157.  type:
  15158.  
  15159.  Type                              Values
  15160.  ────────────────────────────────────────────────────────────────────────────
  15161.  
  15162.  PRIM_AREA                         ABB_COLOR, ABB_BACK_COLOR, ABB_MIX_MODE,
  15163.                                    ABB_BACK_MIX_MODE, ABB_SET, ABB_SYMBOL,
  15164.                                    ABB_REF_POINT
  15165.  
  15166.  PRIM_CHAR                         CBB_COLOR, CBB_BACK_COLOR, CBB_MIX_MODE,
  15167.                                    CBB_BACK_MIX_MODE, CBB_SET, CBB_MODE,
  15168.                                    CBB_BOX, CBB_ANGLE, CBB_SHEAR,
  15169.                                    CBB_DIRECTION
  15170.  
  15171.  PRIM_IMAGE                        IBB_COLOR, IBB_BACK_COLOR, IBB_MIX_MODE,
  15172.                                    IBB_BACK_MIX_MODE
  15173.  
  15174.  PRIM_LINE                         LBB_COLOR, LBB_MIX_MODE, LBB_WIDTH,
  15175.                                    LBB_GEOM_WIDTH, LBB_TYPE, LBB_END,
  15176.                                    LBB_JOIN
  15177.  
  15178.  PRIM_MARKER                       MBB_COLOR, MBB_BACK_COLOR,
  15179.                                    MBB_BACK_MIX_MODE, MBB_SET, MBB_SYMBOL,
  15180.                                    MBB_BOX, MBB_MIX_MODE
  15181.  
  15182.  
  15183.  
  15184.  If this parameter is zero, no attributes are set, regardless of the value of
  15185.  the pbunAttrs parameter.
  15186.  
  15187.  pbunAttrs  Points to the buffer that contains attribute values for each
  15188.  default attribute specified by the flAttrMask parameter. The buffer format
  15189.  depends on the primitive type specified by the lPrimType parameter. The
  15190.  following structures can be used for the specified primitive types:
  15191.  
  15192.  Type                              Structure
  15193.  ────────────────────────────────────────────────────────────────────────────
  15194.  
  15195.  PRIM_AREA                         AREABUNDLE
  15196.  
  15197.  PRIM_CHAR                         CHARBUNDLE
  15198.  
  15199.  PRIM_IMAGE                        IMAGEBUNDLE
  15200.  
  15201.  PRIM_LINE                         LINEBUNDLE
  15202.  
  15203.  PRIM_MARKER                       MARKERBUNDLE
  15204.  
  15205.  
  15206.  
  15207.  Return Value
  15208.  
  15209.  The return value is GPI_OK if the function is successful or GPI_ERROR if an
  15210.  error occurs.
  15211.  
  15212.  
  15213.  Errors
  15214.  
  15215.  Use the WinGetLastError function to retrieve the error value, which may be
  15216.  one of the following:
  15217.  
  15218.      PMERR_HUGE_FONTS_NOT_SUPPORTED
  15219.      PMERR_INV_BACKGROUND_COL_ATTR
  15220.      PMERR_INV_CHAR_ANGLE_ATTR
  15221.      PMERR_INV_CHAR_DIRECTION_ATTR
  15222.      PMERR_INV_CHAR_MODE_ATTR
  15223.      PMERR_INV_CHAR_SET_ATTR
  15224.      PMERR_INV_CHAR_SHEAR_ATTR
  15225.      PMERR_INV_COLOR_ATTR
  15226.      PMERR_INV_COORDINATE
  15227.      PMERR_INV_GEOM_LINE_WIDTH_ATTR
  15228.      PMERR_INV_HPS
  15229.      PMERR_INV_LINE_END_ATTR
  15230.      PMERR_INV_LINE_JOIN_ATTR
  15231.      PMERR_INV_LINE_TYPE_ATTR
  15232.      PMERR_INV_LINE_WIDTH_ATTR
  15233.      PMERR_INV_MARKER_SET_ATTR
  15234.      PMERR_INV_MARKER_SYMBOL_ATTR
  15235.      PMERR_INV_MIX_ATTR
  15236.      PMERR_INV_PATTERN_ATTR
  15237.      PMERR_INV_PATTERN_SET_ATTR
  15238.      PMERR_INV_PATTERN_SET_FONT
  15239.      PMERR_INV_PRIMITIVE_TYPE
  15240.      PMERR_PS_BUSY
  15241.      PMERR_UNSUPPORTED_ATTR
  15242.      PMERR_UNSUPPORTED_ATTR_VALUE
  15243.  
  15244.  
  15245.  
  15246.  
  15247.  
  15248.  Comments
  15249.  
  15250.  Setting the default attributes for a primitive does not immediately affect
  15251.  the current attributes. The system uses the default attributes only when the
  15252.  presentation space is reset or when the GpiSetAttrs function is used to set
  15253.  the defaults. The default attributes are reset when the presentation space
  15254.  is reset using the GRES_SEGMENT or GRES_ALL options of the GpiResetPS
  15255.  function.
  15256.  
  15257.  If an attempt is made to set an invalid default value, none of the specified
  15258.  default attribute values change. Some invalid default attribute values (for
  15259.  example, certain color and mix values), however, may not be detected until
  15260.  the attribute is used.
  15261.  
  15262.  
  15263.  See Also
  15264.  
  15265.  GpiQueryDefAttrs, GpiSetAttrs
  15266.  
  15267.  
  15268.  █    GpiSetDefTag
  15269.  ────────────────────────────────────────────────────────────────────────────
  15270.  
  15271.  BOOL GpiSetDefTag  (hps, lTag)
  15272.  
  15273.  HPS  hps;                         /*presentation-space handle */
  15274.  
  15275.  LONG  lTag;                       /*tag */
  15276.  
  15277.  
  15278.  The GpiSetDefTag function sets the default primitive tag. A primitive tag is
  15279.  a way to identify a primitive stored in a segment.
  15280.  
  15281.  
  15282.  Parameters
  15283.  
  15284.  hps  Identifies the presentation space.
  15285.  
  15286.  lTag  Specifies the tag. It must be an integer value.
  15287.  
  15288.  
  15289.  Return Value
  15290.  
  15291.  The return value is GPI_OK if the function is successful or GPI_ERROR if an
  15292.  error occurs.
  15293.  
  15294.  
  15295.  Errors
  15296.  
  15297.  Use the WinGetLastError function to retrieve the error value, which may be
  15298.  the following:
  15299.  
  15300.       PMERR_INV_HPS
  15301.       PMERR_INV_MICROPS_FUNCTION
  15302.       PMERR_PS_BUSY
  15303.  
  15304.  
  15305.  
  15306.  
  15307.  
  15308.  See Also
  15309.  
  15310.  GpiCorrelateChain, GpiCorrelateFrom, GpiCorrelateSegment, GpiQueryDefTag
  15311.  
  15312.  
  15313.  █    GpiSetDefViewingLimits
  15314.  ────────────────────────────────────────────────────────────────────────────
  15315.  
  15316.  BOOL GpiSetDefViewingLimits  (hps, prclLimits)
  15317.  
  15318.  HPS  hps;                         /*presentation-space handle */
  15319.  
  15320.  PRECTL  prclLimits;               /*pointer to structure with viewing
  15321.                                    limits */
  15322.  
  15323.  
  15324.  The GpiSetDefViewingLimits function sets the default viewing limits. The
  15325.  default viewing limits define the values given to the viewing limits of a
  15326.  presentation space whenever that presentation space is reset. (The viewing
  15327.  limits specify a rectangle in model space that the system uses to clip
  15328.  output.) A presentation space can be reset using the GpiResetPS function.
  15329.  
  15330.  
  15331.  Parameters
  15332.  
  15333.  hps  Identifies the presentation space.
  15334.  
  15335.  prclLimits  Points to the RECTL structure that contains the coordinates of
  15336.  the default viewing limits. The RECTL structure has the following form:
  15337.  
  15338.  typedef struct _RECTL {
  15339.      LONG  xLeft;
  15340.      LONG  yBottom;
  15341.      LONG  xRight;
  15342.      LONG  yTop;
  15343.  } RECTL;
  15344.  
  15345.  
  15346.  
  15347.  
  15348.  For a full description, see Chapter 4, "Types, Macros, Structures."
  15349.  
  15350.  
  15351.  Return Value
  15352.  
  15353.  The return value is GPI_OK if the function is successful or GPI_ERROR if an
  15354.  error occurs.
  15355.  
  15356.  
  15357.  Errors
  15358.  
  15359.  Use the WinGetLastError function to retrieve the error value, which may be
  15360.  one of the following:
  15361.  
  15362.       PMERR_INV_COORDINATE
  15363.       PMERR_INV_HPS
  15364.       PMERR_INV_VIEWING_LIMITS
  15365.       PMERR_PS_BUSY
  15366.  
  15367.  
  15368.  
  15369.  
  15370.  
  15371.  Comments
  15372.  
  15373.  Setting the default viewing limits does not immediately affect the
  15374.  viewing-limits parameters. The system uses the default viewing limits only
  15375.  when the presentation space is reset. The default viewing limits are reset
  15376.  when the presentation space is reset using the GRES_SEGMENT or GRES_ALL
  15377.  options of the GpiResetPS function. The reset values for the default viewing
  15378.  limits are all of model space, meaning nothing is clipped.
  15379.  
  15380.  
  15381.  See Also
  15382.  
  15383.  GpiQueryDefViewingLimits, GpiSetViewingLimits
  15384.  
  15385.  
  15386.  █    GpiSetPS
  15387.  ────────────────────────────────────────────────────────────────────────────
  15388.  
  15389.  BOOL GpiSetPS  (hps, psizl, flOptions)
  15390.  
  15391.  HPS  hps;                         /*presentation-space handle */
  15392.  
  15393.  PSIZEL  psizl;                    /*address of structure for
  15394.                                    presentation-space size */
  15395.  
  15396.  ULONG  flOptions;                 /*options */
  15397.  
  15398.  
  15399.  The GpiSetPS function sets the page size and units for the presentation
  15400.  space. This function is often used to change the device transformation for
  15401.  the presentation space.
  15402.  
  15403.  
  15404.  Parameters
  15405.  
  15406.  hps  Identifies the presentation space.
  15407.  
  15408.  psizl  Points to the SIZEL structure that contains the size of the
  15409.  presentation space. The SIZEL structure has the following form:
  15410.  
  15411.  typedef struct _SIZEL {
  15412.      LONG cx;
  15413.      LONG cy;
  15414.  } SIZEL;
  15415.  
  15416.  
  15417.  
  15418.  
  15419.  For a full description, see Chapter 4, "Types, Macros, Structures."
  15420.  
  15421.  flOptions  Specifies the presentation-space options. The options define the
  15422.  page unit for the presentation space. Although the flOptions parameter can
  15423.  include many other options (as specified by the GpiCreatePS function), the
  15424.  GpiSetPS function ignores all but the following options:
  15425.  
  15426.  Option                            Meaning
  15427.  ────────────────────────────────────────────────────────────────────────────
  15428.  
  15429.  PU_ARBITRARY                      Sets the page units to pels, but permits
  15430.                                    the units to be modified later by using
  15431.                                    the GpiSetPageViewport function.
  15432.  
  15433.  PU_HIENGLISH                      Sets the units to 0.001 inch.
  15434.  
  15435.  PU_HIMETRIC                       Sets the units to 0.01 millimeter.
  15436.  
  15437.  PU_LOENGLISH                      Sets the units to 0.01 inch.
  15438.  
  15439.  PU_LOMETRIC                       Sets the units to 0.1 millimeter.
  15440.  
  15441.  PU_PELS                           Sets the units to pels.
  15442.  
  15443.  PU_TWIPS                          Sets the units to 1/1440 inch (1/20
  15444.                                    point).
  15445.  
  15446.  GPIF_DEFAULT                      Specifies that coordinates are stored as
  15447.                                    4-byte integers (LONG). This value is
  15448.                                    the same as GPIF_LONG.
  15449.  
  15450.  GPIF_SHORT                        Specifies that coordinates are stored as
  15451.                                    2-byte integers.
  15452.  
  15453.  GPIF_LONG                         Specifies that coordinates are stored as
  15454.                                    4-byte integers.
  15455.  
  15456.  PS_NORESET                        Specifies that the presentation space
  15457.                                    cannot be fully reset, and that a reset
  15458.                                    equivalent to GRES_SEGMENTS is performed.
  15459.                                    (Otherwise, a full reset, equivalent to
  15460.                                    GRES_ALL, is performed.)
  15461.  
  15462.  
  15463.  
  15464.  Return Value
  15465.  
  15466.  The return value is GPI_OK if the function is successful or GPI_ERROR if an
  15467.  error occurs.
  15468.  
  15469.  
  15470.  Errors
  15471.  
  15472.  Use the WinGetLastError function to retrieve the error value, which may be
  15473.  one of the following:
  15474.  
  15475.       PMERR_INV_HDC
  15476.       PMERR_INV_HPS
  15477.       PMERR_INV_OR_INCOMPAT_OPTIONS
  15478.       PMERR_INV_PS
  15479.       PMERR_PS_BUSY
  15480.  
  15481.  
  15482.  
  15483.  
  15484.  
  15485.  Comments
  15486.  
  15487.  The GpiSetPS function does not affect the device context associated with the
  15488.  presentation space. This means the device context already associated remains
  15489.  associated. Also, the function does not change the type of presentation
  15490.  space. (Presentation-space types include the micro-presentation space and
  15491.  the normal presentation space.)
  15492.  
  15493.  When this function is called, it resets the presentation space to a state
  15494.  that is equivalent to setting the value GRES_ALL in the GpiResetPS function.
  15495.  
  15496.  
  15497.  
  15498.  See Also
  15499.  
  15500.  GpiCreatePS, GpiResetPS
  15501.  
  15502.  
  15503.  Corrections
  15504.  
  15505.  GpiSetPS can be used to set the storage format for the presentation space by
  15506.  specifying one of the constants GPIF_DEFAULT, GPIF_LONG, or GPIF_SHORT. The
  15507.  PS_NORESET constant prevents the presentation space from being completely
  15508.  reset.
  15509.  
  15510.  
  15511.  █    GpiSetViewingLimits
  15512.  ────────────────────────────────────────────────────────────────────────────
  15513.  
  15514.  BOOL GpiSetViewingLimits  (hps, prclLimits)
  15515.  
  15516.  HPS  hps;                         /*presentation-space handle */
  15517.  
  15518.  PRECTL  prclLimits;               /*address of structure with viewing
  15519.                                    limits */
  15520.  
  15521.  
  15522.  The GpiSetViewingLimits function sets the viewing limits. The viewing limits
  15523.  specify a rectangle in model space that the system uses to clip output. The
  15524.  viewing limits include all points inside the rectangle and all points on the
  15525.  left and bottom edges, but do not include points on the right and top edges.
  15526.  Points on these edges are clipped.
  15527.  
  15528.  The GpiSetViewingLimits function can be used in a segment to set the viewing
  15529.  limits for subsequent primitives in the segment. The viewing limits also
  15530.  apply to any called segments, unless the called segment itself sets the
  15531.  viewing limits.
  15532.  
  15533.  
  15534.  Parameters
  15535.  
  15536.  hps  Identifies the presentation space.
  15537.  
  15538.  prclLimits  Points to the RECTL structure that contains the coordinates of
  15539.  the viewing limits. The RECTL structure has the following form:
  15540.  
  15541.  typedef struct _RECTL {
  15542.      LONG  xLeft;
  15543.      LONG  yBottom;
  15544.      LONG  xRight;
  15545.      LONG  yTop;
  15546.  } RECTL;
  15547.  
  15548.  
  15549.  
  15550.  
  15551.  For a full description, see Chapter 4, "Types, Macros, Structures."
  15552.  
  15553.  
  15554.  Return Value
  15555.  
  15556.  The return value is GPI_OK if the function is successful or GPI_ERROR if an
  15557.  error occurs.
  15558.  
  15559.  
  15560.  Errors
  15561.  
  15562.  Use the WinGetLastError function to retrieve the error value, which may be
  15563.  one of the following:
  15564.  
  15565.       PMERR_INV_COORDINATE
  15566.       PMERR_INV_HPS
  15567.       PMERR_INV_VIEWING_LIMITS
  15568.       PMERR_PS_BUSY
  15569.  
  15570.  
  15571.  
  15572.  
  15573.  
  15574.  Comments
  15575.  
  15576.  Unless the segments in the picture chain have the fast-chaining attribute,
  15577.  the system resets the default viewing limits when each segment in the chain
  15578.  is drawn. The default viewing limits include all model space─that is,
  15579.  nothing is clipped.
  15580.  
  15581.  The segment and model transformations do not affect the viewing limits, but
  15582.  the viewing limits are affected by the current viewing and default viewing
  15583.  transformations.
  15584.  
  15585.  If either the left boundary is greater than the right or the bottom boundary
  15586.  is greater than the top, a null rectangle is defined, and all points are
  15587.  clipped.
  15588.  
  15589.  
  15590.  See Also
  15591.  
  15592.  GpiQueryViewingLimits, GpiSetAttrMode
  15593.  
  15594.  
  15595.  Corrections
  15596.  
  15597.  If either the left boundary is greater than the right or the bottom boundary
  15598.  is greater than the top, a null rectangle is defined, and all points are
  15599.  clipped.
  15600.  
  15601.  
  15602.  █    GpiTranslate
  15603.  ────────────────────────────────────────────────────────────────────────────
  15604.  
  15605.  BOOL GpiTranslate  (hps, pmatlf, flType, pptl)
  15606.  
  15607.  HPS  hps;                         /*presentation-space handle */
  15608.  
  15609.  PMATRIXLF  pmatlf;                /*pointer to structure with matrix */
  15610.  
  15611.  LONG  flType;                     /*transformation type */
  15612.  
  15613.  PPOINTL  pptl;                    /*pointer to structure with point data
  15614.                                    */
  15615.  
  15616.  
  15617.  The GpiTranslate function creates a transformation that can be used to
  15618.  translate (move) an object a specified direction and distance. GpiTranslate
  15619.  either adds the specified translation to an existing transformation or
  15620.  replaces the existing transformation. The new transformation can be used in
  15621.  a subsequent call to any transformation function.
  15622.  
  15623.  
  15624.  Parameters
  15625.  
  15626.  hps  Identifies the presentation space.
  15627.  
  15628.  pmatlf  Points to the MATRIXLF structure that contains the transformation
  15629.  matrix. The MATRIXLF structure has the following form:
  15630.  
  15631.  typedef struct _MATRIXLF {
  15632.      FIXED fxM11;
  15633.      FIXED fxM12;
  15634.      LONG  lM13;
  15635.      FIXED fxM21;
  15636.      FIXED fxM22;
  15637.      LONG  lM23;
  15638.      LONG  lM31;
  15639.      LONG  lM32;
  15640.      LONG  lM33;
  15641.  } MATRIXLF;
  15642.  
  15643.  
  15644.  
  15645.  
  15646.  For a full description, see Chapter 4, "Types, Macros, Structures."
  15647.  
  15648.  flType  Specifies how a specified matrix should be used to modify the
  15649.  transformation. It can be one of the following values:
  15650.  
  15651.  Value                             Meaning
  15652.  ────────────────────────────────────────────────────────────────────────────
  15653.  
  15654.  TRANSFORM_ADD                     Additive. The specified transformation
  15655.                                    matrix is combined with the existing
  15656.                                    transformation, with the existing
  15657.                                    transformation first, the new
  15658.                                    transformation second. This option is
  15659.                                    useful for incremental updates to
  15660.                                    transformations.
  15661.  
  15662.  TRANSFORM_REPLACE                 New/replace. The previous transformation
  15663.                                    is discarded and replaced by the
  15664.                                    specified transformation matrix.
  15665.  
  15666.  
  15667.  
  15668.  pptl  Points to the POINTL structure that contains the coordinates of a
  15669.  point, relative to the origin, that defines the required translation. The
  15670.  POINTL structure has the following form:
  15671.  
  15672.  typedef struct _POINTL {
  15673.      LONG  x;
  15674.      LONG  y;
  15675.  } POINTL;
  15676.  
  15677.  
  15678.  
  15679.  
  15680.  
  15681.  Return Value
  15682.  
  15683.  The return value is GPI_OK if the function is successful or GPI_ERROR if an
  15684.  error occurs.
  15685.  
  15686.  
  15687.  Errors
  15688.  
  15689.  Use the WinGetLastError function to retrieve the error value, which may be
  15690.  the following:
  15691.  
  15692.       PMERR_INV_TRANSFORM_TYPE
  15693.  
  15694.  
  15695.  
  15696.  
  15697.  
  15698.  See Also
  15699.  
  15700.  GpiRotate, GpiScale, GpiSetDefaultViewMatrix, GpiSetModelTransformMatrix,
  15701.  GpiSetSegmentTransformMatrix, GpiSetViewingTransformMatrix
  15702.  
  15703.  
  15704.  █    GpiUnloadFonts
  15705.  ────────────────────────────────────────────────────────────────────────────
  15706.  
  15707.  BOOL GpiUnloadFonts  (hab, pszModName)
  15708.  
  15709.  HAB  hab;                         /*anchor-block handle */
  15710.  
  15711.  PSZ  pszModName;                  /*address of the module name */
  15712.  
  15713.  
  15714.  The GpiUnloadFonts function unloads font definitions that were previously
  15715.  loaded from the resource file specified by the pszModName parameter. Before
  15716.  unloading fonts, the application must delete any local identifiers
  15717.  previously assigned to the fonts. The function unloads the fonts for the
  15718.  application only. If any other applications have loaded the fonts, they
  15719.  remain available for those applications.
  15720.  
  15721.  
  15722.  Parameters
  15723.  
  15724.  hab  Identifies the anchor block.
  15725.  
  15726.  pszModName  Points to a null-terminated string. This string must be a valid
  15727.  MS OS/2 filename. If it does not specify a path and the filename extension,
  15728.  the function appends the default extension (.dll) and searches for the font
  15729.  resource file in the directories specified by the libpath command in the
  15730.  config.sys file.
  15731.  
  15732.  
  15733.  Return Value
  15734.  
  15735.  The return value is GPI_OK if the function is successful or GPI_ERROR if an
  15736.  error occurred.
  15737.  
  15738.  
  15739.  Errors
  15740.  
  15741.  Use the WinGetLastError function to retrieve the error value, which may be
  15742.  one of the following:
  15743.  
  15744.       PMERR_FONT_FILE_NOT_LOADED
  15745.       PMERR_FONT_NOT_LOADED
  15746.       PMERR_OWN_SET_ID_REFS
  15747.  
  15748.  
  15749.  
  15750.  
  15751.  
  15752.  See Also
  15753.  
  15754.  GpiCreateLogFont, GpiDeleteSetId, GpiLoadFonts, GpiSetCharSet
  15755.  
  15756.  
  15757.  Corrections
  15758.  
  15759.  Before unloading fonts, the application must delete any local identifiers
  15760.  previously assigned to the fonts.
  15761.  
  15762.  
  15763.  █    GpiWCBitBlt
  15764.  ────────────────────────────────────────────────────────────────────────────
  15765.  
  15766.  LONG GpiWCBitBlt  (hps, hbm, cPoints, aptl, lRop, flOptions)
  15767.  
  15768.  HPS  hps;                         /*presentation-space handle */
  15769.  
  15770.  HBITMAP  hbm;                     /*bitmap handle */
  15771.  
  15772.  LONG  cPoints;                    /*number of points */
  15773.  
  15774.  PPOINTL  aptl;                    /*address of structure with points */
  15775.  
  15776.  LONG  lRop;                       /*mixing function */
  15777.  
  15778.  ULONG  flOptions;                 /*options */
  15779.  
  15780.  
  15781.  The GpiWCBitBlt function copies a bitmap to a presentation space. It can
  15782.  also modify the bitmap within a rectangle in a presentation space. The exact
  15783.  operation carried out by GpiWCBitBlt depends on the raster operation
  15784.  specified by the lRop parameter.
  15785.  
  15786.  If lRop directs GpiWCBitBlt to copy a bitmap, the function copies the bitmap
  15787.  specified by hbm to the presentation space. The presentation space must be
  15788.  associated with a device context for the display, for memory, or for some
  15789.  other suitable raster device. The aptl parameter points to an array of
  15790.  points that specify the corners of a rectangle in the bitmap as well as the
  15791.  corners of the rectangle in the presentation space to receive the bitmap.
  15792.  The bitmap rectangle is specified in device coordinates; the
  15793.  presentation-space rectangle in world coordinates. If the bitmap and
  15794.  presentation-space rectangles are not the same (after converting the
  15795.  presentation space to device coordinates), GpiWCBitBlt stretches or
  15796.  compresses the bitmap to fit the presentation-space rectangle.
  15797.  
  15798.  If lRop directs GpiWCBitBlt to modify a bitmap, the function uses the raster
  15799.  operation to determine how to alter the bits in a rectangle in the
  15800.  presentation space. Raster operations include changes such as inverting
  15801.  existing bits, replacing bits with pattern bits, and mixing existing and
  15802.  pattern bits to create new colors. For some raster operations, the function
  15803.  mixes the bits of the bitmap with the presentation space and/or pattern
  15804.  bits.
  15805.  
  15806.  
  15807.  Parameters
  15808.  
  15809.  hps  Identifies the presentation space.
  15810.  
  15811.  hbm  Identifies the bitmap.
  15812.  
  15813.  cPoints  Specifies the number of points pointed to by the aptl parameter. It
  15814.  must be 4.
  15815.  
  15816.  aptl  Points to an array of POINTL structures that contains the number of
  15817.  points specified in the cPoints parameter. The points must be given in the
  15818.  following order:
  15819.  
  15820.  Element index                     Coordinate
  15821.  ────────────────────────────────────────────────────────────────────────────
  15822.  
  15823.  0                                 Specifies the lower-left corner of the
  15824.                                    target rectangle in world coordinates.
  15825.  
  15826.  1                                 Specifies the upper-right corner of the
  15827.                                    target rectangle in world coordinates.
  15828.  
  15829.  2                                 Specifies the lower-left corner of the
  15830.                                    source rectangle in device coordinates.
  15831.  
  15832.  3                                 Specifies the upper-right corner of the
  15833.                                    source rectangle in device coordinates.
  15834.  
  15835.  
  15836.  
  15837.  The POINTL structure has the following form:
  15838.  
  15839.  typedef struct _POINTL  {
  15840.      LONG  x;
  15841.      LONG  y;
  15842.  } POINTL;
  15843.  
  15844.  
  15845.  
  15846.  
  15847.  For a full description, see Chapter 4, "Types, Macros, Structures."
  15848.  
  15849.  lRop  Specifies the raster operation for the function. It can be any value
  15850.  in the range 0 through 255 or one of the following values, which represent
  15851.  common raster operations:
  15852.  
  15853.  Value                             Meaning
  15854.  ────────────────────────────────────────────────────────────────────────────
  15855.  
  15856.  ROP_DSTINVERT                     Inverts the target.
  15857.  
  15858.  ROP_MERGECOPY                     Combines the source and the pattern
  15859.                                    using the bitwise AND operator.
  15860.  
  15861.  ROP_MERGEPAINT                    Combines the inverse of the source and
  15862.                                    the target using the bitwise OR operator.
  15863.  
  15864.  ROP_NOTSRCCOPY                    Copies the inverse of the source to the
  15865.                                    target.
  15866.  
  15867.  ROP_NOTSRCERASE                   Combines the inverse of the source and
  15868.                                    the inverse of the target bitmaps using
  15869.                                    the bitwise AND operator.
  15870.  
  15871.  ROP_ONE                           Sets all target pels to 1.
  15872.  
  15873.  ROP_PATCOPY                       Copies the pattern to the target.
  15874.  
  15875.  ROP_PATINVERT                     Combines the target and the pattern
  15876.                                    using the bitwise exclusive XOR operator.
  15877.  
  15878.  ROP_PATPAINT                      Combines the inverse of the source, the
  15879.                                    pattern, and target using the bitwise OR
  15880.                                    operator.
  15881.  
  15882.  ROP_SRCAND                        Combines the source and target bitmaps
  15883.                                    using the bitwise AND operator.
  15884.  
  15885.  ROP_SRCCOPY                       Copies the source bitmap to the target.
  15886.  
  15887.  ROP_SRCERASE                      Combines the source and the inverse of
  15888.                                    the target bitmaps using the bitwise AND
  15889.                                    operator.
  15890.  
  15891.  ROP_SRCINVERT                     Combines the source and target bitmaps
  15892.                                    using the bitwise exclusive OR operator.
  15893.  
  15894.  ROP_SRCPAINT                      Combines the source and target bitmaps
  15895.                                    using the bitwise OR operator.
  15896.  
  15897.  ROP_ZERO                          Sets all target pels to 0.
  15898.  
  15899.  
  15900.  
  15901.  flOptions  Specifies how to compress a bitmap if the target rectangle is
  15902.  smaller than the source. It can be one of the following values:
  15903.  
  15904.  Value                             Meaning
  15905.  ────────────────────────────────────────────────────────────────────────────
  15906.  
  15907.  BBO_AND                           Compresses two rows or columns into one
  15908.                                    by combining them with the bitwise AND
  15909.                                    operator. This value is useful for
  15910.                                    compressing bitmaps that have black
  15911.                                    images on a white background.
  15912.  
  15913.  BBO_OR                            Compresses two rows or columns into one
  15914.                                    by combining them with the bitwise OR
  15915.                                    operator. This value is the default and
  15916.                                    is useful for compressing bitmaps that
  15917.                                    have white images on a black background.
  15918.  
  15919.  BBO_IGNORE                        Compresses two rows or columns by
  15920.                                    throwing one out. This value is useful
  15921.                                    for compressing color bitmaps.
  15922.  
  15923.  
  15924.  
  15925.  All values in the range 0x0100 to 0xFF00 are reserved for privately
  15926.  supported modes for particular devices.
  15927.  
  15928.  
  15929.  Return Value
  15930.  
  15931.  The return value is GPI_OK or GPI_HITS if the function is successful (it is
  15932.  GPI_HITS if the detectable attribute is set for the presentation space and a
  15933.  correlation hit occurs). The return value is GPI_ERROR if an error occurs.
  15934.  
  15935.  
  15936.  Errors
  15937.  
  15938.  Use the WinGetLastError function to retrieve the error value, which may be
  15939.  one of the following:
  15940.  
  15941.       PMERR_BASE_ERROR
  15942.       PMERR_BITMAP_NOT_SELECTED
  15943.       PMERR_INCOMPATIBLE_BITMAP
  15944.       PMERR_INV_BITBLT_MIX
  15945.       PMERR_INV_BITBLT_STYLE
  15946.       PMERR_INV_COORDINATE
  15947.       PMERR_INV_DC_TYPE
  15948.       PMERR_INV_HBITMAP
  15949.       PMERR_INV_HDC
  15950.       PMERR_INV_IN_AREA
  15951.       PMERR_INV_IN_PATH
  15952.       PMERR_INV_LENGTH_OR_COUNT
  15953.  
  15954.  
  15955.  
  15956.  
  15957.  
  15958.  Comments
  15959.  
  15960.  The GpiWCBitBlt function can be used in an open segment. If the drawing mode
  15961.  is DM_DRAWANDRETAIN or DM_RETAIN, the function builds a graphics order in
  15962.  the current open segment. The order identifies the bitmap handle and uses
  15963.  uses long or short coordinates, as determined by the presentation-space
  15964.  format.
  15965.  
  15966.  GpiWCBitBlt does not affect the pels in the upper and right boundaries of
  15967.  the presentation-space rectangle. This means the function draws up to but
  15968.  does not include those pels. Also, the function ignores any rotation
  15969.  transformations.
  15970.  
  15971.  If the lRop parameter includes a pattern, GpiWCBitBlt uses the current area
  15972.  color, area background color, pattern set, and pattern symbol of the
  15973.  presentation space. Although the function may stretch or compress the
  15974.  bitmap, it never stretches or compresses the pattern.
  15975.  
  15976.  If the presentation-space and the bitmap have different color formats,
  15977.  GpiWCBitBlt converts the bitmap color format as it copies the bitmap. This
  15978.  applies to bitmaps copied to a device context having a monochrome format. To
  15979.  convert a monochrome bitmap to a color bitmap, GpiWCBitBlt converts 1 pels
  15980.  to the presentation foreground color, and 0 pels to the current-area
  15981.  background color.
  15982.  
  15983.  
  15984.  Example
  15985.  
  15986.  This example uses GpiWCBitBlt to copy and compress a bitmap in a
  15987.  presentation space. The function copies the bitmap that is 100 pels wide and
  15988.  100 pels high into a 50-by-50-pel rectangle at the location (300,400). Since
  15989.  the raster operation is ROP_SRCCOPY, GpiWCBitBlt replaces the image
  15990.  previously in the presentation-space rectangle. The function compresses the
  15991.  bitmap to fit the new rectangle by discarding extra rows and columns as
  15992.  specified by the BBO_IGNORE option.
  15993.  
  15994.  HPS hps;
  15995.  HBITMAP hbm;
  15996.  POINTL aptl[4] = {
  15997.      300, 400,      /* lower-left corner of target             */
  15998.      350, 450,      /* upper-right corner of target            */
  15999.      0, 0,          /* lower-left corner of source             */
  16000.      100, 100 };    /* upper-right corner of source            */
  16001.  
  16002.  GpiWCBitBlt(hps,   /* presentation space                      */
  16003.      hbm,           /* bitmap handle                           */
  16004.      4L,            /* four points needed to compress          */
  16005.      aptl,          /* points for source and target rectangles */
  16006.      ROP_SRCCOPY,   /* copy source replacing target            */
  16007.      BBO_IGNORE);   /* discard extra rows and columns          */
  16008.  
  16009.  
  16010.  
  16011.  
  16012.  
  16013.  See Also
  16014.  
  16015.  DevOpenDC, GpiBitBlt, GpiCreateBitmap, GpiLoadBitmap, GpiSetBitmap,
  16016.  GpiSetBitmapDimension, GpiSetBitmapId
  16017.  
  16018.  
  16019.  Corrections
  16020.  
  16021.  For the aptl parameter, the element indexes are 0, 1, 2, and 3. The array
  16022.  has at most four elements, not five.
  16023.  
  16024.  
  16025.  █    HM_ACTIONBAR_COMMAND
  16026.  ────────────────────────────────────────────────────────────────────────────
  16027.  
  16028.  
  16029.  HM_ACTIONBAR_COMMAND
  16030.  usCmd = (USHORT) SHORT1FROMMP(mp1);   /* command value */
  16031.  
  16032.  
  16033.  
  16034.  
  16035.  The HM_ACTIONBAR_COMMAND message is sent when the user chooses a command
  16036.  from an application-supplied menu in the help window. The application should
  16037.  carry out the command identified by the usCmd parameter.
  16038.  
  16039.  
  16040.  Parameters
  16041.  
  16042.  usCmd  Low word of mp1. Specifies the command value.
  16043.  
  16044.  
  16045.  Return Value
  16046.  
  16047.  
  16048.  
  16049.  An application should return zero if it processes this message.
  16050.  
  16051.  
  16052.  Comments
  16053.  
  16054.  Applications can replace the menu in a help window by specifying a menu ID
  16055.  in the HELPINIT structure used when the help instance is created by using
  16056.  the WinCreateHelpInstance function. If an application replaces the menu, it
  16057.  receives the HM_ACTIONBAR_COMMAND message when the user chooses a command
  16058.  from the menu. Application-supplied menus should have command values in the
  16059.  range 0x7F00 through 0x7FFF.
  16060.  
  16061.  
  16062.  See Also
  16063.  
  16064.  WinCreateHelpInstance
  16065.  
  16066.  
  16067.  █    HM_CREATE_HELP_TABLE
  16068.  ────────────────────────────────────────────────────────────────────────────
  16069.  
  16070.  
  16071.  HM_CREATE_HELP_TABLE
  16072.  mp1 = MPFROMP((PHELPTABLE) phtHelpTable);  /* pointer to help table  */
  16073.  mp2 = 0L;                                  /* not used, must be zero */
  16074.  
  16075.  
  16076.  An application sends an HM_CREATE_HELP_TABLE message to a help window to set
  16077.  the help table for the help instance. The system uses the specified help
  16078.  table to locate help-panel IDs on subsequent requests for help.
  16079.  
  16080.  
  16081.  Parameters
  16082.  
  16083.  phtHelpTable  Low and high words of mp1. Points to the HELPTABLE structure
  16084.  that contains the help-table information. The HELPTABLE structure has the
  16085.  following form:
  16086.  
  16087.  typedef struct _HELPTABLE {
  16088.      USHORT          idAppWindow;
  16089.      PHELPSUBTABLE   phstHelpSubTable;
  16090.      USHORT          idExtPanel;
  16091.  } HELPTABLE;
  16092.  
  16093.  
  16094.  
  16095.  
  16096.  For a full description, see Chapter 4, "Types, Macros, Structures."
  16097.  
  16098.  
  16099.  Return Value
  16100.  
  16101.  The return value is FALSE.
  16102.  
  16103.  
  16104.  Comments
  16105.  
  16106.  An application can use this message to replace the initial help table of a
  16107.  help instance or to set the table if no initial help table is given. The
  16108.  initial help table is specified in the HELPINIT structure used when the help
  16109.  instance is created by using the WinCreateHelpInstance function. This
  16110.  message replaces the help table without freeing any memory or resources
  16111.  associated with the initial help table.
  16112.  
  16113.  The application must allocate space for the help table and fill the table
  16114.  with appropriate values before sending this message. The system does not
  16115.  check the validity of the help-table contents.
  16116.  
  16117.  
  16118.  See Also
  16119.  
  16120.  WinCreateHelpInstance, HM_LOAD_HELP_TABLE
  16121.  
  16122.  
  16123.  █    HM_DISMISS_WINDOW
  16124.  ────────────────────────────────────────────────────────────────────────────
  16125.  
  16126.  
  16127.  HM_DISMISS_WINDOW
  16128.  mp1 = 0L;    /* not used, must be zero */
  16129.  mp2 = 0L;    /* not used, must be zero */
  16130.  
  16131.  
  16132.  An application sends an HM_DISMISS_WINDOW message to a help window to close
  16133.  the help window. Closing the help window does not destroy the help instance.
  16134.  
  16135.  
  16136.  
  16137.  Parameters
  16138.  
  16139.  This message does not use any parameters.
  16140.  
  16141.  
  16142.  Return Value
  16143.  
  16144.  The return value is FALSE if the help window is closed. It is TRUE if the
  16145.  help window was already closed.
  16146.  
  16147.  
  16148.  Comments
  16149.  
  16150.  A help window is a modeless window. This means the user can view help and
  16151.  return to the application window without closing the help window. An
  16152.  application can use the HM_DISMISS_WINDOW message to close the help window
  16153.  if the user has not closed it.
  16154.  
  16155.  
  16156.  See Also
  16157.  
  16158.  WinDestroyHelpInstance
  16159.  
  16160.  
  16161.  █    HM_DISPLAY_HELP
  16162.  ────────────────────────────────────────────────────────────────────────────
  16163.  
  16164.  
  16165.  HM_DISPLAY_HELP
  16166.  mp1 = MPFROMP((PVOID) pHelpPanel);   /* panel ID or pointer to name */
  16167.  mp2 = MPFROMSHORT((USHORT) usTypeFlag); /* ID or name flag          */
  16168.  
  16169.  
  16170.  An application sends an HM_DISPLAY_HELP message to a help window to display
  16171.  a specific help panel.
  16172.  
  16173.  
  16174.  Parameters
  16175.  
  16176.  pHelpPanel  Low and high words of mp1. Points to a help-panel ID, points to
  16177.  a null-terminated help-panel name, or contains the help-panel ID in the low
  16178.  word and 0x0000 in the high word.
  16179.  
  16180.  usTypeFlag  Low word of mp2. Specifies whether the pHelpPanel parameter
  16181.  specifies a help-panel ID or name. The usTypeFlag parameter can be one of
  16182.  the following values:
  16183.  
  16184.  Value                             Meaning
  16185.  ────────────────────────────────────────────────────────────────────────────
  16186.  
  16187.  HM_RESOURCEID                     Specifies that pHelpPanel points to the
  16188.                                    help-panel ID or contains the help-panel
  16189.                                    ID in the low word.
  16190.  
  16191.  HM_PANELNAME                      Specifies that pHelpPanel points to the
  16192.                                    null-terminated help-panel name.
  16193.  
  16194.  
  16195.  
  16196.  Return Value
  16197.  
  16198.  The return value is FALSE if the help panel is displayed. Otherwise, it is
  16199.  an error value, which may be one of the following:
  16200.  
  16201.       HMERR_DATABASE_NOT_OPEN
  16202.       HMERR_PANEL_NOT_FOUND
  16203.       HMERR_READ_LIB_FILE
  16204.  
  16205.  
  16206.  
  16207.  
  16208.  
  16209.  Comments
  16210.  
  16211.  The system searches for the specified panel in the help libraries opened for
  16212.  the help window and displays the first matching panel found.
  16213.  
  16214.  
  16215.  See Also
  16216.  
  16217.  HM_EXT_HELP, HM_HELP_CONTENTS, HM_HELP_INDEX, HM_KEYS_HELP
  16218.  
  16219.  
  16220.  █    HM_ERROR
  16221.  ────────────────────────────────────────────────────────────────────────────
  16222.  
  16223.  
  16224.  HM_ERROR
  16225.  ulErrorCode = (ULONG) LONGFROMMP(mp1);    /* error type */
  16226.  
  16227.  
  16228.  The HM_ERROR message is sent to notify an application of an error in a help
  16229.  window─errors that occur while the user views help. It does not notify the
  16230.  application of errors that result from messages sent by the application.
  16231.  
  16232.  
  16233.  Parameters
  16234.  
  16235.  ulErrorCode  Low and high words of mp1. Specifies an error value, which may
  16236.  be one of the following:
  16237.  
  16238.       HMERR_ALLOCATE_SEGMENT
  16239.       HMERR_CLOSE_LIB_FILE
  16240.       HMERR_CONTENT_NOT_FOUND
  16241.       HMERR_DATABASE_NOT_OPEN
  16242.       HMERR_FREE_MEMORY
  16243.       HMERR_HELP_INSTANCE_UNDEFINE
  16244.       HMERR_HELP_INST_CALLED_INVALID
  16245.       HMERR_HELPITEM_NOT_FOUND
  16246.       HMERR_HELPTABLE_UNDEFINE
  16247.       HMERR_INDEX_NOT_FOUND
  16248.       HMERR_INVALID_ASSOC_APP_WND
  16249.       HMERR_INVALID_ASSOC_HELP_INST
  16250.       HMERR_INVALID_DESTROY_HELP_INST
  16251.       HMERR_INVALID_HELPSUBITEM_SIZE
  16252.       HMERR_INVALID_HELP_INSTANCE_HDL
  16253.       HMERR_INVALID_LIB_FILE
  16254.       HMERR_INVALID_QUERY_APP_WND
  16255.       HMERR_NO_FRAME_WND_IN_CHAIN
  16256.       HMERR_NO_HELP_INST_IN_CHAIN
  16257.       HMERR_NO_MEMORY
  16258.       HMERR_OPEN_LIB_FILE
  16259.       HMERR_PANEL_NOT_FOUND
  16260.       HMERR_READ_LIB_FILE
  16261.  
  16262.  
  16263.  
  16264.  
  16265.  
  16266.  Return Value
  16267.  
  16268.  
  16269.  
  16270.  An application should return zero if it processes this message.
  16271.  
  16272.  
  16273.  Comments
  16274.  
  16275.  Because a help window does not display error messages to the user, the
  16276.  application should display its own messages when it receives an HM_ERROR
  16277.  message.
  16278.  
  16279.  If an error occurs when creating the help instance using the
  16280.  WinCreateHelpInstance function, the system copies the error value to the
  16281.  ulReturnCode field in the HELPINIT structure used with
  16282.  WinCreateHelpInstance. If an error occurs for another function or for a
  16283.  message sent to a help window, the return value from the function or message
  16284.  sent specifies the error.
  16285.  
  16286.  
  16287.  See Also
  16288.  
  16289.  WinCreateHelpInstance
  16290.  
  16291.  
  16292.  
  16293.  
  16294.  
  16295.  █    HM_EXT_HELP
  16296.  ────────────────────────────────────────────────────────────────────────────
  16297.  
  16298.  
  16299.  HM_EXT_HELP
  16300.  mp1 = 0L;    /* not used, must be zero */
  16301.  mp2 = 0L;    /* not used, must be zero */
  16302.  
  16303.  
  16304.  An application sends an HM_EXT_HELP message to a help window to display the
  16305.  extended help panel.
  16306.  
  16307.  
  16308.  Parameters
  16309.  
  16310.  This message does not use any parameters.
  16311.  
  16312.  
  16313.  Return Value
  16314.  
  16315.  The return value is FALSE if the extended help panel is displayed.
  16316.  Otherwise, it is an error value, which may be one of the following:
  16317.  
  16318.       HMERR_DATABASE_NOT_OPEN
  16319.       HMERR_PANEL_NOT_FOUND
  16320.       HMERR_READ_LIB_FILE
  16321.  
  16322.  
  16323.  
  16324.  
  16325.  
  16326.  Comments
  16327.  
  16328.  For this message to display an extended help panel, the help table for the
  16329.  help instance must specify a help-panel ID that corresponds to the active
  16330.  window. (For example, the idExtPanel in the HELPTABLE structure used with
  16331.  the WinCreateHelpInstance function must be set to a valid help-panel ID.) If
  16332.  the help table specifies zero for the extended help-panel ID, the system
  16333.  sends the HM_EXT_HELP_UNDEFINED message to the application. In this case,
  16334.  the application should carry out some default action, such as displaying an
  16335.  error message or using the HM_DISPLAY_HELP message to display a help panel.
  16336.  
  16337.  
  16338.  See Also
  16339.  
  16340.  HM_DISPLAY_HELP, HM_EXT_HELP_UNDEFINED, HM_HELP_INDEX, HM_KEYS_HELP
  16341.  
  16342.  
  16343.  █    HM_EXT_HELP_UNDEFINED
  16344.  ────────────────────────────────────────────────────────────────────────────
  16345.  
  16346.  
  16347.  HM_EXT_HELP_UNDEFINED
  16348.  
  16349.  
  16350.  The HM_EXT_HELP_UNDEFINED message notifies the application that an extended
  16351.  help panel is not defined for the active window.
  16352.  
  16353.  
  16354.  Parameters
  16355.  
  16356.  This message does not use any parameters.
  16357.  
  16358.  
  16359.  Return Value
  16360.  
  16361.  
  16362.  
  16363.  An application should return zero if it processes this message.
  16364.  
  16365.  
  16366.  Comments
  16367.  
  16368.  The system displays extended help only if the help table for the help
  16369.  instance specifies a help-panel ID that corresponds to the active window.
  16370.  (For example, the idExtPanel in the HELPTABLE structure used with the
  16371.  WinCreateHelpInstance function must be set to a valid help-panel ID.) If the
  16372.  help table specifies zero for the extended help-panel ID, the system sends
  16373.  the HM_EXT_HELP_UNDEFINED message to the application. In this case, the
  16374.  application should carry out some default action, such as displaying an
  16375.  error message or using the HM_DISPLAY_HELP message to display a help panel.
  16376.  
  16377.  
  16378.  See Also
  16379.  
  16380.  HM_DISPLAY_HELP, HM_EXT_HELP
  16381.  
  16382.  
  16383.  █    HM_HELP_CONTENTS
  16384.  ────────────────────────────────────────────────────────────────────────────
  16385.  
  16386.  
  16387.  HM_HELP_CONTENTS
  16388.  mp1 = 0L;    /* not used, must be zero */
  16389.  mp2 = 0L;    /* not used, must be zero */
  16390.  
  16391.  
  16392.  An application sends an HM_HELP_CONTENTS message to a help window to display
  16393.  the table of contents for the open help library.
  16394.  
  16395.  
  16396.  Parameters
  16397.  
  16398.  This message does not use any parameters.
  16399.  
  16400.  
  16401.  Return Value
  16402.  
  16403.  The return value is FALSE if the table of contents is displayed. Otherwise,
  16404.  it is an error value, which may be one of the following:
  16405.  
  16406.       HMERR_DATABASE_NOT_OPEN
  16407.       HMERR_PANEL_NOT_FOUND
  16408.       HMERR_READ_LIB_FILE
  16409.  
  16410.  
  16411.  
  16412.  
  16413.  
  16414.  See Also
  16415.  
  16416.  HM_DISPLAY_HELP, HM_HELP_INDEX, HM_KEYS_HELP
  16417.  
  16418.  
  16419.  █    HM_HELP_INDEX
  16420.  ────────────────────────────────────────────────────────────────────────────
  16421.  
  16422.  
  16423.  HM_HELP_INDEX
  16424.  mp1 = 0L;    /* not used, must be zero */
  16425.  mp2 = 0L;    /* not used, must be zero */
  16426.  
  16427.  
  16428.  An application sends an HM_HELP_INDEX message to a help window to display
  16429.  the index for the open help library.
  16430.  
  16431.  
  16432.  Parameters
  16433.  
  16434.  This message does not use any parameters.
  16435.  
  16436.  
  16437.  Return Value
  16438.  
  16439.  The return value is FALSE if the index is displayed. Otherwise, it is an
  16440.  error value, which may be one of the following:
  16441.  
  16442.       HMERR_DATABASE_NOT_OPEN
  16443.       HMERR_PANEL_NOT_FOUND
  16444.       HMERR_READ_LIB_FILE
  16445.  
  16446.  
  16447.  
  16448.  
  16449.  
  16450.  See Also
  16451.  
  16452.  HM_DISPLAY_HELP, HM_HELP_CONTENTS, HM_KEYS_HELP
  16453.  
  16454.  
  16455.  █    HM_HELPSUBITEM_NOT_FOUND
  16456.  ────────────────────────────────────────────────────────────────────────────
  16457.  
  16458.  
  16459.  HM_HELPSUBITEM_NOT_FOUND
  16460.  usMode = (USHORT) SHORT1FROMMP(mp1);       /* help mode              */
  16461.  idTopic = (USHORT) SHORT1FROMMP(mp2);      /* window ID for topic    */
  16462.  idSubTopic = (USHORT) SHORT2FROMMP(mp2);   /* window ID for subtopic */
  16463.  
  16464.  
  16465.  The HM_HELPSUBITEM_NOT_FOUND message notifies the application that the
  16466.  system failed to find a help panel in response to a user request for help.
  16467.  
  16468.  
  16469.  Parameters
  16470.  
  16471.  usMode  Low word of mp1. Specifies the context of the help request. This
  16472.  parameter can be one of the following values:
  16473.  
  16474.  Value                             Meaning
  16475.  ────────────────────────────────────────────────────────────────────────────
  16476.  
  16477.  HLPM_FRAME                        The help request is for a focus window
  16478.                                    that is a child window of the client
  16479.                                    window.
  16480.  
  16481.  HLPM_MENU                         The help request is for a selected menu
  16482.                                    item or submenu.
  16483.  
  16484.  HLPM_WINDOW                       The help request is for a focus window
  16485.                                    that is not a child window of the client
  16486.                                    window.
  16487.  
  16488.  
  16489.  
  16490.  idTopic  Low word of mp2. Specifies the ID of the active frame or dialog
  16491.  window or the submenu that contains the selection.
  16492.  
  16493.  idSubTopic  High word of mp2. Specifies the ID of the window that has the
  16494.  keyboard focus or the menu item that contains the selection.
  16495.  
  16496.  
  16497.  Return Value
  16498.  
  16499.  An application should return FALSE to direct the system to display the
  16500.  extended help panel for the active window. An application should return TRUE
  16501.  to direct the system to do nothing.
  16502.  
  16503.  
  16504.  Comments
  16505.  
  16506.  When an application receives this message, it should carry out a default
  16507.  action, such as displaying an error message or using the HM_DISPLAY_HELP
  16508.  message to display an explicitly specified help panel, or it can return
  16509.  FALSE to direct the system to display the extended help panel. If the
  16510.  application displays an error message or a help panel, it must return TRUE
  16511.  to prevent the system from displaying the extended help panel.
  16512.  
  16513.  
  16514.  See Also
  16515.  
  16516.  HM_DISPLAY_HELP, HM_ERROR
  16517.  
  16518.  
  16519.  █    HM_INFORM
  16520.  ────────────────────────────────────────────────────────────────────────────
  16521.  
  16522.  
  16523.  HM_INFORM
  16524.  idPanel = (USHORT) SHORT1FROMMP(mp1);    /* help-panel ID */
  16525.  
  16526.  
  16527.  The HM_INFORM message notifies an application that the user has chosen a
  16528.  hypertext field in the help window.
  16529.  
  16530.  
  16531.  Parameters
  16532.  
  16533.  idPanel  Low word of mp1. Specifies the help-panel ID associated with the
  16534.  hypertext field.
  16535.  
  16536.  
  16537.  Return Value
  16538.  
  16539.  
  16540.  
  16541.  An application should return zero if it processes this message.
  16542.  
  16543.  
  16544.  Comments
  16545.  
  16546.  The system sends an HM_INFORM message only if the corresponding hypertext
  16547.  field was created using the :inform tag. The value of the idPanel parameter
  16548.  is the number specified with the tag. This is usually a help-panel ID, but
  16549.  it can be any number. When an application receives the HM_INFORM message, it
  16550.  can carry out any action; however, after the application returns from the
  16551.  message, the system displays the corresponding help panel if one exists.
  16552.  
  16553.  
  16554.  See Also
  16555.  
  16556.  HM_DISPLAY_HELP
  16557.  
  16558.  
  16559.  █    HM_KEYS_HELP
  16560.  ────────────────────────────────────────────────────────────────────────────
  16561.  
  16562.  
  16563.  HM_KEYS_HELP
  16564.  mp1 = 0L;    /* not used, must be zero */
  16565.  mp2 = 0L;    /* not used, must be zero */
  16566.  
  16567.  
  16568.  An application sends an HM_KEYS_HELP message to a help window to display the
  16569.  help panel that contains information about the application keys.
  16570.  
  16571.  
  16572.  Parameters
  16573.  
  16574.  This message does not use any parameters.
  16575.  
  16576.  
  16577.  Return Value
  16578.  
  16579.  The return value is FALSE if the keys-help panel is displayed. Otherwise, it
  16580.  is an error value, which may be one of the following:
  16581.  
  16582.       HMERR_DATABASE_NOT_OPEN
  16583.       HMERR_PANEL_NOT_FOUND
  16584.       HMERR_READ_LIB_FILE
  16585.  
  16586.  
  16587.  
  16588.  
  16589.  
  16590.  Comments
  16591.  
  16592.  Because the keys-help-panel ID is not specified in the help table, the
  16593.  system sends an HM_QUERY_KEYS_HELP message to the window associated with the
  16594.  help window or to the active window. If the application returns the
  16595.  keys-help-panel ID, the system displays the keys-help window.
  16596.  
  16597.  
  16598.  See Also
  16599.  
  16600.  HM_DISPLAY_HELP, HM_EXT_HELP, HM_HELP_CONTENTS, HM_HELP_INDEX
  16601.  
  16602.  
  16603.  █    HM_LOAD_HELP_TABLE
  16604.  ────────────────────────────────────────────────────────────────────────────
  16605.  
  16606.  
  16607.  HM_LOAD_HELP_TABLE
  16608.  mp1 = MPFROM2SHORT(0xFFFF, (USHORT) idHelpTable); /* help-table ID */
  16609.  mp2 = MPFROMSHORT((USHORT) hmodModule);    /* module with resource */
  16610.  
  16611.  
  16612.  An application sends an HM_LOAD_HELP_TABLE message to a help window to
  16613.  replace the existing help table (if any) with a help-table resource.
  16614.  
  16615.  
  16616.  Parameters
  16617.  
  16618.  idHelpTable  Low word of mp1. Specifies the resource ID of the help-table
  16619.  resource.
  16620.  
  16621.  hmodModule  Low word of mp2. Identifies the module that contains the
  16622.  help-table resource.
  16623.  
  16624.  
  16625.  Return Value
  16626.  
  16627.  The return value is FALSE.
  16628.  
  16629.  
  16630.  Comments
  16631.  
  16632.  Applications can use this message to replace the initial help table of a
  16633.  help instance or to set the table if no initial help table is given. The
  16634.  initial help table is specified in the HELPINIT structure used when the help
  16635.  instance is created by using the WinCreateHelpInstance function. This
  16636.  message replaces the help table without freeing any memory or resources
  16637.  associated with the initial help table.
  16638.  
  16639.  
  16640.  See Also
  16641.  
  16642.  WinCreateHelpInstance, HM_CREATE_HELP_TABLE
  16643.  
  16644.  
  16645.  █    HM_QUERY_KEYS_HELP
  16646.  ────────────────────────────────────────────────────────────────────────────
  16647.  
  16648.  
  16649.  HM_QUERY_KEYS_HELP
  16650.  mp1 = 0L;    /* not used, must be zero */
  16651.  mp2 = 0L;    /* not used, must be zero */
  16652.  
  16653.  
  16654.  The HM_QUERY_KEYS_HELP message is sent to an application to retrieve the
  16655.  keys-help-panel ID.
  16656.  
  16657.  
  16658.  Parameters
  16659.  
  16660.  This message does not use any parameters.
  16661.  
  16662.  
  16663.  Return Value
  16664.  
  16665.  An application should return the keys-help-panel ID. If no keys-help panel
  16666.  exists, the application should return an alternate panel ID, such as the ID
  16667.  for extended help.
  16668.  
  16669.  
  16670.  Comments
  16671.  
  16672.  The system uses the returned ID to display the corresponding help panel. If
  16673.  the return value is not a valid help-panel ID, no help is displayed.
  16674.  
  16675.  
  16676.  See Also
  16677.  
  16678.  HM_KEYS_HELP
  16679.  
  16680.  
  16681.  █    HM_REPLACE_HELP_FOR_HELP
  16682.  ────────────────────────────────────────────────────────────────────────────
  16683.  
  16684.  
  16685.  HM_REPLACE_HELP_FOR_HELP
  16686.  mp1 = MPFROMSHORT(idHelpForHelpPanel);  /* help-panel ID          */
  16687.  mp2 = 0L;                               /* not used, must be zero */
  16688.  
  16689.  
  16690.  An application sends an HM_REPLACE_HELP_FOR_HELP message to a help window to
  16691.  replace the general help panel (supplied by the system) with a specified
  16692.  help panel.
  16693.  
  16694.  
  16695.  Parameters
  16696.  
  16697.  idHelpForHelpPanel  Low word of mp1. Specifies a help-panel ID.
  16698.  
  16699.  
  16700.  Return Value
  16701.  
  16702.  The return value is zero.
  16703.  
  16704.  
  16705.  Comments
  16706.  
  16707.  A help window displays the general help panel whenever an application
  16708.  specifies zero for the help-panel ID in an HM_DISPLAY_HELP message. The
  16709.  general help panel is initially set by the system when the help instance is
  16710.  created; applications can replace the system-supplied help at any time.
  16711.  Applications that modify the help-window menu should also replace the
  16712.  general help information.
  16713.  
  16714.  
  16715.  See Also
  16716.  
  16717.  HM_DISPLAY_HELP
  16718.  
  16719.  
  16720.  █    HM_SET_ACTIVE_WINDOW
  16721.  ────────────────────────────────────────────────────────────────────────────
  16722.  
  16723.  
  16724.  HM_SET_ACTIVE_WINDOW
  16725.  mp1 = MPFROMHWND(hwndActiveWindow);   /* active-window handle      */
  16726.  mp2 = MPFROMHWND(hwndRelativeWindow); /* application-window handle */
  16727.  
  16728.  
  16729.  An application sends an HM_SET_ACTIVE_WINDOW message to a help window to set
  16730.  the active and relative windows. The active window is the window to which
  16731.  the system sends help messages. The relative window is the window next to
  16732.  which the system displays the help window.
  16733.  
  16734.  
  16735.  Parameters
  16736.  
  16737.  hwndActiveWindow  Low and high words of mp1. Identifies the active window.
  16738.  This value can be a window handle or NULL. If this parameter is NULL, the
  16739.  active and relative windows are determined by the system.
  16740.  
  16741.  hwndRelativeWindow  Low and high words of mp2. Identifies the relative
  16742.  window. This value can be a window handle or HWND_PARENT. If the value is
  16743.  HWND_PARENT, the system sets the relative window to be the parent window of
  16744.  the active window.
  16745.  
  16746.  
  16747.  Return Value
  16748.  
  16749.  The return value is FALSE.
  16750.  
  16751.  
  16752.  See Also
  16753.  
  16754.  WinAssociateHelpInstance
  16755.  
  16756.  
  16757.  █    HM_SET_HELP_LIBRARY_NAME
  16758.  ────────────────────────────────────────────────────────────────────────────
  16759.  
  16760.  
  16761.  HM_SET_HELP_LIBRARY_NAME
  16762.  mp1 = MPFROMP(pszHelpLibraryName); /* pointer to help-library name */
  16763.  mp2 = 0L;                          /* not used, must be zero       */
  16764.  
  16765.  
  16766.  An application sends an HM_SET_HELP_LIBRARY_NAME message to Help Manager to
  16767.  identify the help library to search.
  16768.  
  16769.  
  16770.  Parameters
  16771.  
  16772.  pszHelpLibraryName  Low and high words of mp1. Points to the string that
  16773.  contains the help-library name used by Help Manager when it searches for the
  16774.  requested help topic.
  16775.  
  16776.  
  16777.  Comments
  16778.  
  16779.  Sending an HM_SET_HELP_LIBRARY_NAME message replaces the current help
  16780.  library with the library specified.
  16781.  
  16782.  
  16783.  █    HM_SET_HELP_WINDOW_TITLE
  16784.  ────────────────────────────────────────────────────────────────────────────
  16785.  
  16786.  
  16787.  HM_SET_HELP_WINDOW_TITLE
  16788.  mp1 = MPFROMP(pszHelpWindowTitle);  /* pointer to new title   */
  16789.  mp2 = 0L;                           /* not used, must be zero */
  16790.  
  16791.  
  16792.  An application sends an HM_SET_HELP_WINDOW_TITLE message to a help window to
  16793.  change the window title.
  16794.  
  16795.  
  16796.  Parameters
  16797.  
  16798.  pszHelpWindowTitle  Low and high words of mp1. Points to the null-terminated
  16799.  string that contains the new Help-window title.
  16800.  
  16801.  
  16802.  Return Value
  16803.  
  16804.  The return value is FALSE if the window title is set. Otherwise, it is an
  16805.  error value, which may be one of the following:
  16806.  
  16807.      HMERR_ALLOCATE_SEGMENT
  16808.      HMERR_NO_MEMORY
  16809.  
  16810.  
  16811.  
  16812.  
  16813.  
  16814.  Comments
  16815.  
  16816.  The initial window title is specified by setting the pszHelpWindowTitle
  16817.  field in the HELPINIT structure used when the help instance is created by
  16818.  using the WinCreateHelpInstance function. The system allocates memory to
  16819.  save the title and frees the memory when the HM_SET_HELP_WINDOW_TITLE
  16820.  message is used to change the title.
  16821.  
  16822.  
  16823.  See Also
  16824.  
  16825.  WinCreateHelpInstance
  16826.  
  16827.  
  16828.  █    HM_SET_SHOW_PANEL_ID
  16829.  ────────────────────────────────────────────────────────────────────────────
  16830.  
  16831.  
  16832.  HM_SET_SHOW_PANEL_ID
  16833.  mp1 = MPFROMSHORT(fVisible);   /* help-panel ID flag     */
  16834.  mp2 = 0L;                      /* not used, must be zero */
  16835.  
  16836.  
  16837.  An application sends an HM_SET_SHOW_PANEL_ID message to a help window to
  16838.  specify whether the window should display the help-panel ID along with the
  16839.  help panel title.
  16840.  
  16841.  
  16842.  Parameters
  16843.  
  16844.  fVisible  Low word of mp1. Specifies whether to display or hide the
  16845.  help-panel ID. This parameter can be one of the following values:
  16846.  
  16847.  Value                             Meaning
  16848.  ────────────────────────────────────────────────────────────────────────────
  16849.  
  16850.  CMIC_HIDE_PANEL_ID                Turns off the show option. The
  16851.                                    help-panel ID is not displayed.
  16852.  
  16853.  CMIC_SHOW_PANEL_ID                Turns on the show option. The help-panel
  16854.                                    ID is displayed. ,
  16855.  
  16856.  CMIC_TOGGLE_PANEL_ID              Toggles the display of the help-panel ID.
  16857.  
  16858.  
  16859.  
  16860.  Return Value
  16861.  
  16862.  The return value is zero.
  16863.  
  16864.  
  16865.  Comments
  16866.  
  16867.  The help window displays the help-panel ID along with the help-panel title
  16868.  in the title bar of the help-panel window. The panel ID is enclosed in
  16869.  brackets.
  16870.  
  16871.  Initially, an application specifies whether to display the help-panel ID by
  16872.  setting the usShowPanelId field in the HELPINIT structure when the help
  16873.  instance is created by using the WinCreateHelpInstance function.
  16874.  
  16875.  
  16876.  See Also
  16877.  
  16878.  WinCreateHelpInstance
  16879.  
  16880.  
  16881.  █    HM_TUTORIAL
  16882.  ────────────────────────────────────────────────────────────────────────────
  16883.  
  16884.  
  16885.  HM_TUTORIAL
  16886.  pszTutorialName = (PSZ) PVOIDFROMMP(mp1); /* pointer to tutorial */
  16887.  
  16888.  
  16889.  The HM_TUTORIAL message is sent to a window when the user chooses the
  16890.  Tutorial command in the help window menu. The application can then invoke
  16891.  its own tutorial program.
  16892.  
  16893.  
  16894.  Parameters
  16895.  
  16896.  pszTutorialName  Low and high words of mp1. Points to the null-terminated
  16897.  tutorial name.
  16898.  
  16899.  
  16900.  Return Value
  16901.  
  16902.  An application should return zero if it processes this message.
  16903.  
  16904.  
  16905.  Comments
  16906.  
  16907.  An application sets the name of the tutorial by setting the pszTutorialName
  16908.  field in the HELPINIT structure used when the help instance is created by
  16909.  using the WinCreateHelpInstance function. If a tutorial name is specified,
  16910.  the help window adds the Tutorial command to its Help menu.
  16911.  
  16912.  
  16913.  See Also
  16914.  
  16915.  WinCreateHelpInstance
  16916.  
  16917.  
  16918.  █    KbdCharIn
  16919.  ────────────────────────────────────────────────────────────────────────────
  16920.  
  16921.  USHORT KbdCharIn  (pkbci, fWait, hkbd)
  16922.  
  16923.  PKBDKEYINFO  pkbci;               /*pointer to structure for keystroke
  16924.                                    info. */
  16925.  
  16926.  USHORT  fWait;                    /*wait/no-wait flag */
  16927.  
  16928.  HKBD  hkbd;                       /*keyboard handle */
  16929.  
  16930.  
  16931.  The KbdCharIn function retrieves character and scan-code information from a
  16932.  logical keyboard. The function copies the information to a specified
  16933.  structure. Keystroke information includes the character value of a given
  16934.  key, the scan code, the keystroke status, the state of the shift keys, and
  16935.  the system time (in milliseconds) when the keystroke occurred.
  16936.  
  16937.  The KbdCharIn function is a family API function.
  16938.  
  16939.  
  16940.  Parameters
  16941.  
  16942.  pkbci  Points to the KBDKEYINFO structure that receives the keystroke
  16943.  information. The KBDKEYINFO structure has the following form:
  16944.  
  16945.  typedef struct _KBDKEYINFO {
  16946.      UCHAR  chChar;
  16947.      UCHAR  chScan;
  16948.      UCHAR  fbStatus;
  16949.      UCHAR  bNlsShift;
  16950.      USHORT fsState;
  16951.      ULONG  time;
  16952.  } KBDKEYINFO;
  16953.  
  16954.  
  16955.  
  16956.  
  16957.  For a full description, see Chapter 4, "Types, Macros, Structures."
  16958.  
  16959.  fWait  Specifies whether to wait for keystroke information if none is
  16960.  available. If this parameter is IO_WAIT, the function waits for a keystroke
  16961.  if one is not available. If this parameter is IO_NOWAIT, the function
  16962.  returns immediately whether or not it retrieved any keystroke information.
  16963.  The fbStatus field in the KBDKEYINFO structure specifies whether a keystroke
  16964.  is received. The fbStatus field is nonzero if a keystroke is received or
  16965.  zero if not.
  16966.  
  16967.  hkbd  Identifies the logical keyboard. The handle must have been created by
  16968.  using the KbdOpen function.
  16969.  
  16970.  
  16971.  Return Value
  16972.  
  16973.  The return value is zero if the function is successful. Otherwise, it is an
  16974.  error value, which may be one of the following:
  16975.  
  16976.       ERROR_KBD_FOCUS_REQUIRED
  16977.       ERROR_KBD_INVALID_IOWAIT
  16978.       ERROR_KBD_INVALID_HANDLE
  16979.  
  16980.  
  16981.  
  16982.  
  16983.  
  16984.  Comments
  16985.  
  16986.  The KbdCharIn function copies and removes keystroke information from the
  16987.  input buffer of the specified logical keyboard. Although echo mode for the
  16988.  logical keyboard may be turned on, KbdCharIn does not echo the characters it
  16989.  reads. If the keyboard is in ASCII mode, KbdCharIn retrieves keystroke
  16990.  information for each key pressed except shift keys. If the keyboard is in
  16991.  binary mode, KbdCharIn retrieves keystroke information for any key pressed
  16992.  except shift keys. In most cases, a shift key is pressed in combination with
  16993.  other keys to create a single keystroke. In binary mode with shift reporting
  16994.  turned on, a shift key by itself creates a keystroke this function can
  16995.  retrieve. For more information on binary mode and shift-reporting mode, see
  16996.  the KbdSetStatus function.
  16997.  
  16998.  The KbdCharIn function retrieves extended ASCII codes, such as when the ALT
  16999.  key and another key, called the primary key, are pressed simultaneously.
  17000.  
  17001.  When the function retrieves an extended code, it sets the chChar field of
  17002.  the KBDKEYINFO structure to 0x0000 or 0x00E0. It also sets the fbStatus
  17003.  field to EXTENDED_CODE and copies the extended code to the chScan field.
  17004.  Note that both fields need to be examined to determine whether an extended
  17005.  code has been received. The extended code is usually the scan code of the
  17006.  primary key. In ASCII mode, the function retrieves only complete extended
  17007.  codes, which means that if both bytes of the extended code do not fit in the
  17008.  buffer, neither byte is retrieved. For more information on extended ASCII
  17009.  codes, see Appendix C, "Country and Code-Page Information."
  17010.  
  17011.  This function must be called twice to retrieve a code for a double-byte
  17012.  character set (DBCS). If the code retrieved is the first byte of a
  17013.  double-byte character, the fbStatus field of the KBDKEYINFO structure is set
  17014.  to 0x0080.
  17015.  
  17016.  
  17017.  Restrictions
  17018.  
  17019.  In real mode, the following restrictions apply to the KbdCharIn function:
  17020.  
  17021.    ■   It does not copy the system time to the KBDKEYINFO structure and there
  17022.        is no interim character support.
  17023.  
  17024.    ■   It retrieves characters only from the default logical keyboard (handle
  17025.        0).
  17026.  
  17027.    ■   The fbStatus field can be 0x0000 or SHIFT_KEY_IN.
  17028.  
  17029.    ■   The hkbd parameter is ignored.
  17030.  
  17031.  
  17032.  
  17033.  
  17034.  Example
  17035.  
  17036.  This example calls the KbdCharIn function to retrieve a character, and then
  17037.  displays the character on the screen.
  17038.  
  17039.  KBDKEYINFO kbci;
  17040.  KbdCharIn(&kbci,                  /* structure for data */
  17041.      IO_WAIT,                      /* waits for key      */
  17042.      0);                           /* keyboard handle    */
  17043.  VioWrtTTY(&kbci.chChar, 1, 0);
  17044.  
  17045.  
  17046.  
  17047.  
  17048.  
  17049.  See Also
  17050.  
  17051.  KbdGetStatus, KbdOpen, KbdPeek, KbdSetStatus, KbdStringIn
  17052.  
  17053.  
  17054.  Changes
  17055.  
  17056.  In order to allow for input 0x00E0 as a normal character, a new value has
  17057.  been added to the fbStatus field of the KBDKEYINFO structure. In order to
  17058.  detect an extended code, both of the following conditions must be true:
  17059.  
  17060.    ■   chChar must be equal to 0x0000 or 0x00E0
  17061.  
  17062.    ■   fbStatus must be equal to EXTENDED_CHAR
  17063.  
  17064.  
  17065.  
  17066.  
  17067.  █    KbdGetHWID
  17068.  ────────────────────────────────────────────────────────────────────────────
  17069.  
  17070.  USHORT KbdGetHWID  (pkbdhwid, hkbd)
  17071.  
  17072.  PKBDHWID  pkbdhwid;               /*pointer to structure for ID number */
  17073.  
  17074.  HKBD  hkbd;                       /*keyboard handle */
  17075.  
  17076.  
  17077.  The KbdGetHWID function retrieves the hardware ID number of a keyboard.
  17078.  
  17079.  
  17080.  Parameters
  17081.  
  17082.  pkbdhwid  Points to the KBDHWID structure that receives the ID number of the
  17083.  keyboard. The KBDHWID structure has the following form:
  17084.  
  17085.  typedef struct _KBDHWID {
  17086.      USHORT cb;
  17087.      USHORT idKbd;
  17088.      USHORT usReserved1;
  17089.      USHORT usReserved2;
  17090.  } KBDHWID;
  17091.  
  17092.  
  17093.  
  17094.  
  17095.  For a full description, see Chapter 4, "Types, Macros, Structures."
  17096.  
  17097.  hkbd  Identifies the logical keyboard. This handle must have been created by
  17098.  using the KbdOpen function.
  17099.  
  17100.  
  17101.  Return Value
  17102.  
  17103.  The return value is zero if the function is successful. Otherwise, it is an
  17104.  error value, which may be one of the following:
  17105.  
  17106.       ERROR_KBD_DETACHED
  17107.       ERROR_KBD_INVALID_HANDLE
  17108.       ERROR_KBD_PARAMETER
  17109.  
  17110.  
  17111.  
  17112.  
  17113.  
  17114.  Example
  17115.  
  17116.  This example opens a logical keyboard, and then calls the KbdGetHWID
  17117.  function to retrieve the hardware ID number of that keyboard.
  17118.  
  17119.      HKBD hkbd;
  17120.      KBDHWID kbhw;
  17121.  
  17122.      KbdOpen(&hkbd);                /* opens keyboard          */
  17123.      KbdGetFocus(IO_WAIT, hkbd);    /* gets focus for keyboard */
  17124.      kbhw.cb = sizeof(kbhw);        /* sets structure length   */
  17125.      KbdGetHWID(&kbhw, hkbd);       /* gets ID number          */
  17126.  
  17127.  
  17128.  
  17129.  
  17130.  
  17131.  See Also
  17132.  
  17133.  DosDevIOCtl, KbdOpen
  17134.  
  17135.  
  17136.  █    KbdRegister
  17137.  ────────────────────────────────────────────────────────────────────────────
  17138.  
  17139.  USHORT KbdRegister  (pszModuleName, pszEntryName, fFunctions)
  17140.  
  17141.  PSZ  pszModuleName;               /*pointer to string for module name */
  17142.  
  17143.  PSZ  pszEntryName;                /*pointer to string for entry-point name
  17144.                                    */
  17145.  
  17146.  ULONG  fFunctions;                /*function flags */
  17147.  
  17148.  
  17149.  The KbdRegister function registers a Kbd subsystem for the specified logical
  17150.  keyboard. The function temporarily replaces the specified default Kbd
  17151.  functions with the functions in the specified module. Once KbdRegister
  17152.  replaces a function, MS OS/2 passes any subsequent call to the replaced
  17153.  function to a function in the given module. If a function is not replaced,
  17154.  MS OS/2 continues to call the default Kbd function.
  17155.  
  17156.  
  17157.  Parameters
  17158.  
  17159.  pszModuleName  Points to the null-terminated string that contains the name
  17160.  of the dynamic-link module that specifies the replacement Kbd functions. The
  17161.  string must be a valid filename.
  17162.  
  17163.  pszEntryName  Points to the null-terminated string that contains the name of
  17164.  the dynamic-link entry-point function. For a full description, see the
  17165.  following "Comments" section.
  17166.  
  17167.  fFunctions  Specifies the flags for the functions to be replaced. This
  17168.  parameter can be any combination of the following values:
  17169.  
  17170.  Value                             Meaning
  17171.  ────────────────────────────────────────────────────────────────────────────
  17172.  
  17173.  KR_KBDCHARIN                      Replace KbdCharIn.
  17174.  
  17175.  KR_KBDPEEK                        Replace KbdPeek.
  17176.  
  17177.  KR_KBDFLUSHBUFFER                 Replace KbdFlushBuffer.
  17178.  
  17179.  KR_KBDGETSTATUS                   Replace KbdGetStatus.
  17180.  
  17181.  KR_KBDSETSTATUS                   Replace KbdSetStatus.
  17182.  
  17183.  KR_KBDSTRINGIN                    Replace KbdStringIn.
  17184.  
  17185.  KR_KBDOPEN                        Replace KbdOpen.
  17186.  
  17187.  KR_KBDCLOSE                       Replace KbdClose.
  17188.  
  17189.  KR_KBDGETFOCUS                    Replace KbdGetFocus.
  17190.  
  17191.  KR_KBDFREEFOCUS                   Replace KbdFreeFocus.
  17192.  
  17193.  KR_KBDGETCP                       Replace KbdGetCp.
  17194.  
  17195.  KR_KBDSETCP                       Replace KbdSetCp.
  17196.  
  17197.  KR_KBDXLATE                       Replace KbdXlate.
  17198.  
  17199.  KR_KBDSETCUSTXT                   Replace KbdSetCustXt.
  17200.  
  17201.  KR_KBDGETHWID                     Replace KbdGetHWID.
  17202.  
  17203.  
  17204.  
  17205.  Return Value
  17206.  
  17207.  The return value is zero if the function is successful. Otherwise, it is an
  17208.  error value, which may be one of the following:
  17209.  
  17210.       ERROR_KBD_INVALID_ASCIIZ
  17211.       ERROR_KBD_INVALID_MASK
  17212.       ERROR_KBD_REGISTER
  17213.  
  17214.  
  17215.  
  17216.  
  17217.  
  17218.  Comments
  17219.  
  17220.  MS OS/2 passes a Kbd function to the given module by preparing the stack and
  17221.  calling the function pointed to by the pszEntryName parameter. The specified
  17222.  module must export the entry-point function name. The entry-point function
  17223.  must check the function code on the stack to determine which function is
  17224.  being requested and then pass control to the appropriate function in the
  17225.  module. The entry-point function can then access any additional parameters
  17226.  placed on the stack by the original call to KbdRegister.
  17227.  
  17228.  Only one process in a screen group can use the KbdRegister function at any
  17229.  given time. That is, only one process can replace Kbd functions at any given
  17230.  time. The process can restore the default Kbd functions by calling the
  17231.  KbdDeRegister function. A process can replace Kbd functions any number of
  17232.  times, but only by first restoring the default functions and then
  17233.  reregistering the new functions.
  17234.  
  17235.  The entry-point function (FuncName) must have the following form:
  17236.  
  17237.  SHORT FAR FuncName(selDataSeg, usReserved1, fFunction,
  17238.      ulReserved2, usParam1, usParam2, usParam3, usParam4,
  17239.      usParam5, usParam6)
  17240.  SEL selDataSeg;
  17241.  USHORT usReserved1;
  17242.  USHORT fFunction;
  17243.  ULONG ulReserved2;
  17244.  USHORT usParam1;
  17245.  USHORT usParam2;
  17246.  USHORT usParam3;
  17247.  USHORT usParam4;
  17248.  USHORT usParam5;
  17249.  USHORT usParam6;
  17250.  
  17251.  
  17252.  
  17253.  Parameters                        Description
  17254.  ────────────────────────────────────────────────────────────────────────────
  17255.  
  17256.  selDataSeg                        Specifies the data-segment selector of
  17257.                                    the process that calls the specified Kbd
  17258.                                    function.
  17259.  
  17260.  usReserved1                       Specifies a reserved value that must not
  17261.                                    be changed. This value represents a
  17262.                                    return address for the MS OS/2 function
  17263.                                    that routes Kbd function calls.
  17264.  
  17265.  fFunction                         Specifies the function code of the
  17266.                                    function request. This parameter can be
  17267.                                    one of the following values:
  17268.  
  17269.  
  17270.  
  17271.  Value                             Meaning
  17272.  ────────────────────────────────────────────────────────────────────────────
  17273.  
  17274.  0x0000                            KbdCharIn called.
  17275.  
  17276.  0x0001                            KbdPeek called.
  17277.  
  17278.  0x0002                            KbdFlushBuffer called.
  17279.  
  17280.  0x0003                            KbdGetStatus called.
  17281.  
  17282.  0x0004                            KbdSetStatus called.
  17283.  
  17284.  0x0005                            KbdStringIn called.
  17285.  
  17286.  0x0006                            KbdOpen called.
  17287.  
  17288.  0x0007                            KbdClose called.
  17289.  
  17290.  0x0008                            KbdGetFocus called.
  17291.  
  17292.  0x0009                            KbdFreeFocus called.
  17293.  
  17294.  0x000A                            KbdGetCp called.
  17295.  
  17296.  0x000B                            KbdSetCp called.
  17297.  
  17298.  0x000C                            KbdXlate called.
  17299.  
  17300.  0x000D                            KbdSetCustXt called.
  17301.  
  17302.  0x000E                            KbdGetHWID called.
  17303.  
  17304.  ulReserved2           Specifies a reserved value that must not
  17305.                                    be changed. This value represents the
  17306.                                    return address of the program that calls
  17307.                                    the specified Kbd function.
  17308.  
  17309.  usParam1-usParam6     Specify up to six unsigned values passed with the
  17310.                                    call to the Kbd function. The number and
  17311.                                    type of parameters used depend on the
  17312.                                    specific function.
  17313.  
  17314.  The entry-point function should determine which function is requested and
  17315.  then carry out an appropriate action by using the passed parameters. If
  17316.  necessary, the entry-point function can call a function within the same
  17317.  module to carry out the task. The entry-point or replacement function must
  17318.  leave the stack in the same state as it was received because the return
  17319.  addresses on the stack must be available in the correct order to return
  17320.  control to the program that originally called the KbdRegister function.
  17321.  
  17322.  The registered function should return -1 to call the original function, 0 if
  17323.  no error occurred, or an error value.
  17324.  
  17325.  In general, to access the keyboard the replacement function must use the
  17326.  input-and-output control functions for the keyboard.
  17327.  
  17328.  The KbdRegister function itself cannot be replaced.
  17329.  
  17330.  
  17331.  See Also
  17332.  
  17333.  KbdDeRegister, KbdFlushBuffer
  17334.  
  17335.  
  17336.  Changes
  17337.  
  17338.  The KR_KBDGETTHWID constant for the new function KbdGetHWID has been added
  17339.  to the functions list and also to the return list.
  17340.  
  17341.  
  17342.  █    Menu-Item Attributes
  17343.  ────────────────────────────────────────────────────────────────────────────
  17344.  
  17345.  
  17346.  
  17347.  Menu-item attributes specify the display aspects of a menu item, such as its
  17348.  highlighted state and checked state. Attributes are set when the item is
  17349.  created and typically change frequently as the application runs and the user
  17350.  interacts with the menus.
  17351.  
  17352.  Attribute                         Description
  17353.  ────────────────────────────────────────────────────────────────────────────
  17354.  
  17355.  MIA_CHECKED                       Places a check mark to the left of the
  17356.                                    menu item.
  17357.  
  17358.  MIA_DISABLED                      Disables the menu item. The item is
  17359.                                    drawn halftone and cannot be selected by
  17360.                                    the user. An application should disable
  17361.                                    a menu item when choosing it would be
  17362.                                    inappropriate─for example, a Save-menu
  17363.                                    item should be disabled when no changes
  17364.                                    have occurred since the last save
  17365.                                    operation.
  17366.  
  17367.  MIA_FRAMED                        Places a frame around the menu item.
  17368.                                    With this attribute set, an item in a
  17369.                                    menu bar is framed by vertical lines to
  17370.                                    its left and right; an item in a
  17371.                                    drop-down menu is framed by horizontal
  17372.                                    lines above and below it.
  17373.  
  17374.  MIA_HILITED                       Highlights the menu item by inverting
  17375.                                    the colors of the item name and
  17376.                                    background when the menu item is
  17377.                                    currently selected. The application
  17378.                                    rarely sets this attribute directly,
  17379.                                    relying instead on the default
  17380.                                    processing of user input to set the
  17381.                                    highlighted state of an item.
  17382.  
  17383.  MIA_NODISMISS                     Causes a submenu or menu item to remain
  17384.                                    displayed after the user chooses an item.
  17385.  
  17386.  
  17387.  
  17388.  Changes
  17389.  
  17390.  The MIA_DISABLED and MIA_NODISMISS constants have been added.
  17391.  
  17392.  The MIA_ENABLED constant has been removed.
  17393.  
  17394.  
  17395.  █    MLM_CHARFROMLINE
  17396.  ────────────────────────────────────────────────────────────────────────────
  17397.  
  17398.  
  17399.  MLM_CHARFROMLINE
  17400.  mp1 = MPFROMLONG((LINE) lLineNum);    /* line number            */
  17401.  mp2 = 0L;                             /* not used, must be zero */
  17402.  
  17403.  
  17404.  An application sends an MLM_CHARFROMLINE message to obtain the offset
  17405.  (number of characters from the beginning of the text) of the first character
  17406.  on the specified line in a multiple-line entry field (MLE).
  17407.  
  17408.  
  17409.  Parameters
  17410.  
  17411.  lLineNum  Low and high words of mp1. Specifies the line number. A value of
  17412.  zero specifies the first line. A value of -1 specifies the line that
  17413.  contains the cursor.
  17414.  
  17415.  
  17416.  Return Value
  17417.  
  17418.  The return value is the 32-bit offset of the first character on the
  17419.  specified line.
  17420.  
  17421.  
  17422.  Comments
  17423.  
  17424.  If the lLineNum parameter specifies a line number greater than the line
  17425.  number of the last line of text in the MLE, the insertion point returned
  17426.  will be the point to the right of the last character in the MLE.
  17427.  
  17428.  A line consists of all text up to a carriage return. A line may be displayed
  17429.  as several lines on the screen due to word-wrapping and still be considered
  17430.  a single line when specifying the line number for the lLineNum parameter.
  17431.  
  17432.  Line numbers are zero-based. Therefore, the first line in an MLE is zero.
  17433.  
  17434.  
  17435.  See Also
  17436.  
  17437.  MLM_LINEFROMCHAR
  17438.  
  17439.  
  17440.  █    MLM_CLEAR
  17441.  ────────────────────────────────────────────────────────────────────────────
  17442.  
  17443.  
  17444.  MLM_CLEAR
  17445.  mp1 = 0L;    /* not used, must be zero */
  17446.  mp2 = 0L;    /* not used, must be zero */
  17447.  
  17448.  
  17449.  An application sends an MLM_CLEAR message to clear (delete) selected text in
  17450.  a multiple-line entry field (MLE).
  17451.  
  17452.  
  17453.  Parameters
  17454.  
  17455.  This message does not use any parameters.
  17456.  
  17457.  
  17458.  Return Value
  17459.  
  17460.  The return value is a 32-bit value (ULONG) that specifies the number of
  17461.  characters deleted.
  17462.  
  17463.  
  17464.  See Also
  17465.  
  17466.  MLM_CUT, MLM_DELETE
  17467.  
  17468.  
  17469.  █    MLM_COPY
  17470.  ────────────────────────────────────────────────────────────────────────────
  17471.  
  17472.  
  17473.  MLM_COPY
  17474.  mp1 = 0L;    /* not used, must be zero */
  17475.  mp2 = 0L;    /* not used, must be zero */
  17476.  
  17477.  
  17478.  An application sends an MLM_COPY message to copy selected multiple-line
  17479.  entry field (MLE) text to the clipboard.
  17480.  
  17481.  
  17482.  Parameters
  17483.  
  17484.  This message does not use any parameters.
  17485.  
  17486.  
  17487.  Return Value
  17488.  
  17489.  The return value is a 32-bit value (ULONG) that specifies the number of
  17490.  characters copied to the clipboard.
  17491.  
  17492.  
  17493.  Comments
  17494.  
  17495.  If no text is selected, the previous contents of the clipboard remain
  17496.  unaltered.
  17497.  
  17498.  
  17499.  See Also
  17500.  
  17501.  MLM_CUT, MLM_PASTE
  17502.  
  17503.  
  17504.  █    MLM_CUT
  17505.  ────────────────────────────────────────────────────────────────────────────
  17506.  
  17507.  
  17508.  MLM_CUT
  17509.  mp1 = 0L;    /* not used, must be zero */
  17510.  mp2 = 0L;    /* not used, must be zero */
  17511.  
  17512.  
  17513.  An application sends an MLM_CUT message to copy selected multiple-line
  17514.  entry-field (MLE) text to the clipboard and then clear the selected text.
  17515.  
  17516.  
  17517.  Parameters
  17518.  
  17519.  This message does not use any parameters.
  17520.  
  17521.  
  17522.  Return Value
  17523.  
  17524.  The return value is a 32-bit value (ULONG) that specifies the number of
  17525.  characters copied and cleared.
  17526.  
  17527.  
  17528.  Comments
  17529.  
  17530.  If no text is selected, the previous contents of the clipboard remain
  17531.  unaltered.
  17532.  
  17533.  
  17534.  See Also
  17535.  
  17536.  MLM_COPY, MLM_DELETE, MLM_PASTE
  17537.  
  17538.  
  17539.  █    MLM_DELETE
  17540.  ────────────────────────────────────────────────────────────────────────────
  17541.  
  17542.  
  17543.  MLM_DELETE
  17544.  mp1 = MPFROMLONG((LINE) lBegin);    /* beginning of deletion */
  17545.  mp2 = MPFROMLONG((ULONG) cch);      /* characters to delete  */
  17546.  
  17547.  
  17548.  An application sends an MLM_DELETE message to delete the specified number of
  17549.  characters from a multiple-line entry field (MLE).
  17550.  
  17551.  
  17552.  Parameters
  17553.  
  17554.  lBegin  Low and high words of mp1. Specifies the offset (number of
  17555.  characters from the beginning of the text) of the first character to delete.
  17556.  If this parameter is set to -1, the current selection (if any) is deleted.
  17557.  
  17558.  cch  Low and high words of mp2. Specifies the number of characters to
  17559.  delete. This parameter is ignored if the lBegin parameter is set to -1.
  17560.  
  17561.  
  17562.  Return Value
  17563.  
  17564.  The return value is a 32-bit value (LONG) that specifies the number of
  17565.  characters deleted.
  17566.  
  17567.  
  17568.  See Also
  17569.  
  17570.  MLM_CUT
  17571.  
  17572.  
  17573.  █    MLM_DISABLEREFRESH
  17574.  ────────────────────────────────────────────────────────────────────────────
  17575.  
  17576.  
  17577.  MLM_DISABLEREFRESH
  17578.  mp1 = 0L;    /* not used, must be zero */
  17579.  mp2 = 0L;    /* not used, must be zero */
  17580.  
  17581.  
  17582.  An application sends an MLM_DISABLEREFRESH message to prevent repainting
  17583.  (refresh) of a multiple-line entry field (MLE).
  17584.  
  17585.  
  17586.  Parameters
  17587.  
  17588.  This message does not use any parameters.
  17589.  
  17590.  
  17591.  Return Value
  17592.  
  17593.  The return value is always TRUE.
  17594.  
  17595.  
  17596.  Comments
  17597.  
  17598.  When refresh is disabled, the MLE does not accept any keyboard or mouse
  17599.  input. When the mouse pointer is positioned over the MLE window, the pointer
  17600.  changes to the hourglass shape.
  17601.  
  17602.  
  17603.  See Also
  17604.  
  17605.  MLM_ENABLEREFRESH
  17606.  
  17607.  
  17608.  █    MLM_ENABLEREFRESH
  17609.  ────────────────────────────────────────────────────────────────────────────
  17610.  
  17611.  
  17612.  MLM_ENABLEREFRESH
  17613.  mp1 = 0L;    /* not used, must be zero */
  17614.  mp2 = 0L;    /* not used, must be zero */
  17615.  
  17616.  
  17617.  An application sends an MLM_ENABLEREFRESH message to enable repainting
  17618.  (refresh) of a multiple-line entry field (MLE). While the refresh state is
  17619.  enabled, the entire MLE window is repainted.
  17620.  
  17621.  
  17622.  Parameters
  17623.  
  17624.  This message does not use any parameters.
  17625.  
  17626.  
  17627.  Return Value
  17628.  
  17629.  The return value is always TRUE.
  17630.  
  17631.  
  17632.  See Also
  17633.  
  17634.  MLM_DISABLEREFRESH
  17635.  
  17636.  
  17637.  █    MLM_EXPORT
  17638.  ────────────────────────────────────────────────────────────────────────────
  17639.  
  17640.  
  17641.  MLM_EXPORT
  17642.  mp1 = MPFROMP((PIPT) plOffset);     /* beginning of copy area */
  17643.  mp2 = MPFROMP((PULONG) pcbCopy);    /* bytes to copy          */
  17644.  
  17645.  
  17646.  An application sends an MLM_EXPORT message to export text from a
  17647.  multiple-line entry field (MLE) by copying the specified number of
  17648.  characters from the MLE to the buffer specified by the MLM_SETIMPORTEXPORT
  17649.  message. If all of the specified characters are on a single line, only the
  17650.  specified characters are copied. If the specified characters are on more
  17651.  than one line, the entire line containing the last specified character is
  17652.  copied.
  17653.  
  17654.  
  17655.  Parameters
  17656.  
  17657.  plOffset  Low and high words of mp1. Points to the variable that specifies
  17658.  the offset (number of characters from the beginning of the text) of the
  17659.  first character to copy. A value of -1 specifies the current cursor
  17660.  position. On return, this variable contains the offset to the first
  17661.  character not copied to the buffer.
  17662.  
  17663.  pcbCopy  Low and high words of mp2. Points to the variable that specifies
  17664.  the number of characters to copy. On return, this variable is zero if the
  17665.  number of characters actually copied does not exceed the numbers specified
  17666.  to be copied. It is nonzero if the number of characters specified includes a
  17667.  line break and a portion of another line.
  17668.  
  17669.  
  17670.  Return Value
  17671.  
  17672.  The return value is a 32-bit value (ULONG) that specifies the number of
  17673.  bytes actually copied. This value includes carriage-return and linefeed
  17674.  characters copied to the buffer.
  17675.  
  17676.  
  17677.  Comments
  17678.  
  17679.  The text is copied in the form set by the MLM_FORMAT message. Note that the
  17680.  buffer is not zero-terminated.
  17681.  
  17682.  All exports are done in full characters. Therefore, if the length of the
  17683.  buffer or the number of bytes to be exported results in the last byte
  17684.  transferred being only half of a double-byte character set (DBCS) character,
  17685.  the MLE does not transfer that byte.
  17686.  
  17687.  
  17688.  See Also
  17689.  
  17690.  MLM_FORMAT, MLM_SETIMPORTEXPORT
  17691.  
  17692.  
  17693.  █    MLM_FORMAT
  17694.  ────────────────────────────────────────────────────────────────────────────
  17695.  
  17696.  
  17697.  MLM_FORMAT
  17698.  mp1 = MPFROMSHORT(usFormat);    /* format to set          */
  17699.  mp2 = 0L;                       /* not used, must be zero */
  17700.  
  17701.  
  17702.  An application sends an MLM_FORMAT message to set the format for importing
  17703.  to or exporting from a multiple-line entry field (MLE).
  17704.  
  17705.  
  17706.  Parameters
  17707.  
  17708.  usFormat  Low word of mp1. Specifies the format to set. This parameter can
  17709.  be one of the following values:
  17710.  
  17711.  Value                             Meaning
  17712.  ────────────────────────────────────────────────────────────────────────────
  17713.  
  17714.  MLFIE_CFTEXT                      Specifies the clipboard text format.
  17715.                                    This format uses
  17716.                                    carriage-return/linefeed characters for
  17717.                                    line breaks on export, and recognizes
  17718.                                    linefeed, carriage-return/ linefeed, or
  17719.                                    linefeed/carriage-return characters for
  17720.                                    line breaks on import. This is the
  17721.                                    default format.
  17722.  
  17723.  MLFIE_NOTRANS                     Specifies a format that uses linefeed
  17724.                                    characters for line breaks. This value
  17725.                                    guarantees that any text imported into
  17726.                                    the MLE in this form can be recovered in
  17727.                                    exactly the same form on export.
  17728.  
  17729.  MLFIE_WINFMT                      Specifies the format of the MLE window.
  17730.                                    This format recognizes
  17731.                                    carriage-return/linefeed characters for
  17732.                                    line breaks on import. It ignores the
  17733.                                    sequence
  17734.                                    carriage-return/carriage-return/linefeed.
  17735.                                    On export, it uses
  17736.                                    carriage-return/linefeed characters to
  17737.                                    denote a hard line break and
  17738.                                    carriage-return/carriage-return/linefeed
  17739.                                    characters to denote a soft line break
  17740.                                    caused by word-wrapping.
  17741.  
  17742.  
  17743.  
  17744.  See Also
  17745.  
  17746.  MLM_EXPORT, MLM_IMPORT, MLM_QUERYFORMATLINELENGTH, MLM_QUERYFORMATTEXTLENGTH
  17747.  
  17748.  
  17749.  
  17750.  █    MLM_IMPORT
  17751.  ────────────────────────────────────────────────────────────────────────────
  17752.  
  17753.  
  17754.  MLM_IMPORT
  17755.  mp1 = MPFROMP(plOffset);     /* import offset           */
  17756.  mp2 = MPFROMLONG(cbCopy);    /* number of bytes to copy */
  17757.  
  17758.  
  17759.  An application sends an MLM_IMPORT message to insert the contents of the
  17760.  buffer specified by the MLM_SETIMPORTEXPORT message into the multiple-line
  17761.  entry field (MLE).
  17762.  
  17763.  
  17764.  Parameters
  17765.  
  17766.  plOffset  Low and high words of mp1. Points to the variable that specifies
  17767.  the offset (number of characters from the beginning of the text) to the
  17768.  edit-control buffer where the import buffer is to be inserted. A value of -1
  17769.  specifies the current cursor position. On return, this variable contains the
  17770.  offset to the first character beyond the imported buffer.
  17771.  
  17772.  cbCopy  Low and high words of mp2. Specifies the number of bytes to import.
  17773.  If the last byte transferred is half of a double-byte character or part of a
  17774.  line-break sequence (carriage-return/linefeed), the last character is not
  17775.  transferred.
  17776.  
  17777.  
  17778.  Return Value
  17779.  
  17780.  The return value is a 32-bit value (ULONG) that specifies the number of
  17781.  bytes actually imported. This may be less than the value specified by the
  17782.  cbCopy parameter─if the last byte to copy included only part of a
  17783.  double-byte character or part of a line-break sequence. The return value is
  17784.  zero if the import would overflow the text limit set by the MLM_SETTEXTLIMIT
  17785.  message.
  17786.  
  17787.  
  17788.  Comments
  17789.  
  17790.  The contents of the buffer are interpreted as being in the form set by the
  17791.  MLM_FORMAT message.
  17792.  
  17793.  
  17794.  See Also
  17795.  
  17796.  MLM_FORMAT, MLM_SETIMPORTEXPORT, MLM_SETTEXTLIMIT, MLN_OVERFLOW, WM_CONTROL
  17797.  
  17798.  
  17799.  █    MLM_INSERT
  17800.  ────────────────────────────────────────────────────────────────────────────
  17801.  
  17802.  
  17803.  MLM_INSERT
  17804.  mp1 = MPFROMP(pszBuf);    /* pointer to text        */
  17805.  mp2 = 0L;                 /* not used, must be zero */
  17806.  
  17807.  
  17808.  An application sends an MLM_INSERT message to insert text into a
  17809.  multiple-line entry field (MLE) at the current cursor position.
  17810.  
  17811.  
  17812.  Parameters
  17813.  
  17814.  pszBuf  Low and high words of mp1. Points to the null-terminated string that
  17815.  contains the text to insert.
  17816.  
  17817.  
  17818.  Return Value
  17819.  
  17820.  The return value is TRUE if the text is inserted successfully or FALSE if an
  17821.  error occurs. If the inserted text overflows a text limit or format
  17822.  rectangle, an error occurs and an appropriate notification message is sent.
  17823.  
  17824.  
  17825.  See Also
  17826.  
  17827.  MLN_OVERFLOW, MLN_TEXTOVERFLOW, WM_CONTROL
  17828.  
  17829.  
  17830.  █    MLM_LINEFROMCHAR
  17831.  ────────────────────────────────────────────────────────────────────────────
  17832.  
  17833.  
  17834.  MLM_LINEFROMCHAR
  17835.  mp1 = MPFROMLONG(lOffset);    /* offset of MLE character */
  17836.  mp2 = 0L;                     /* not used, must be zero  */
  17837.  
  17838.  
  17839.  An application sends an MLM_LINEFROMCHAR message to obtain the number of the
  17840.  line that contains the specified character in a multiple-line entry field
  17841.  (MLE).
  17842.  
  17843.  
  17844.  Parameters
  17845.  
  17846.  lOffset  Low and high words of mp1. Specifies the offset (number of
  17847.  characters from the beginning of the text) of the specified character. A
  17848.  value of -1 specifies that the number of the line that contains the cursor
  17849.  is returned. If the offset specified is greater than the total number of
  17850.  characters currently in the MLE, the number of the last line is returned.
  17851.  
  17852.  
  17853.  Return Value
  17854.  
  17855.  The return value is a 32-bit value (ULONG) that specifies the number of the
  17856.  line that contains the specified character.
  17857.  
  17858.  
  17859.  Comments
  17860.  
  17861.  Line numbers are zero-based. Therefore, the first line in an MLE is zero.
  17862.  
  17863.  
  17864.  See Also
  17865.  
  17866.  MLM_CHARFROMLINE
  17867.  
  17868.  
  17869.  █    MLM_PASTE
  17870.  ────────────────────────────────────────────────────────────────────────────
  17871.  
  17872.  
  17873.  MLM_PASTE
  17874.  mp1 = 0L;    /* not used, must be zero */
  17875.  mp2 = 0L;    /* not used, must be zero */
  17876.  
  17877.  
  17878.  An application sends an MLM_PASTE message to copy the contents of the
  17879.  clipboard to a multiple-line entry field (MLE).
  17880.  
  17881.  
  17882.  Parameters
  17883.  
  17884.  This message does not use any parameters.
  17885.  
  17886.  
  17887.  Return Value
  17888.  
  17889.  The return value is a 32-bit value (ULONG) that specifies the number of
  17890.  characters copied. If the clipboard contains an incompatible format, the
  17891.  return value is zero.
  17892.  
  17893.  
  17894.  See Also
  17895.  
  17896.  MLM_COPY, MLM_CUT
  17897.  
  17898.  
  17899.  █    MLM_QUERYBACKCOLOR
  17900.  ────────────────────────────────────────────────────────────────────────────
  17901.  
  17902.  
  17903.  MLM_QUERYBACKCOLOR
  17904.  mp1 = 0L;    /* not used, must be 0 */
  17905.  mp2 = 0L;    /* not used, must be 0 */
  17906.  
  17907.  
  17908.  An application sends an MLM_QUERYBACKCOLOR message to obtain
  17909.  background-color information for a multiple-line entry field (MLE).
  17910.  
  17911.  
  17912.  Parameters
  17913.  
  17914.  This message does not use any parameters.
  17915.  
  17916.  
  17917.  Return Value
  17918.  
  17919.  The return value is a 32-bit value (COLOR) that specifies the background
  17920.  color. It can be one of the following values:
  17921.  
  17922.  Value                             Meaning
  17923.  ────────────────────────────────────────────────────────────────────────────
  17924.  
  17925.  CLR_FALSE                         All color planes are zeros.
  17926.  
  17927.  CLR_TRUE                          All color planes are ones.
  17928.  
  17929.  CLR_DEFAULT                       Default value; same as CLR_NEUTRAL.
  17930.  
  17931.  CLR_WHITE                         White.
  17932.  
  17933.  CLR_BLACK                         Black.
  17934.  
  17935.  CLR_BACKGROUND                    Reset color.
  17936.  
  17937.  CLR_BLUE                          Blue.
  17938.  
  17939.  CLR_RED                           Red.
  17940.  
  17941.  CLR_PINK                          Pink.
  17942.  
  17943.  CLR_GREEN                         Green.
  17944.  
  17945.  CLR_CYAN                          Cyan.
  17946.  
  17947.  CLR_YELLOW                        Yellow.
  17948.  
  17949.  CLR_NEUTRAL                       Neutral.
  17950.  
  17951.  CLR_DARKGRAY                      Dark gray.
  17952.  
  17953.  CLR_DARKBLUE                      Dark blue.
  17954.  
  17955.  CLR_DARKRED                       Dark red.
  17956.  
  17957.  CLR_DARKPINK                      Dark pink.
  17958.  
  17959.  CLR_DARKGREEN                     Dark green.
  17960.  
  17961.  CLR_DARKCYAN                      Dark cyan.
  17962.  
  17963.  CLR_BROWN                         Brown.
  17964.  
  17965.  CLR_PALEGRAY                      Light gray.
  17966.  
  17967.  
  17968.  
  17969.  See Also
  17970.  
  17971.  MLM_QUERYTEXTCOLOR, MLM_SETBACKCOLOR
  17972.  
  17973.  
  17974.  █    MLM_QUERYCHANGED
  17975.  ────────────────────────────────────────────────────────────────────────────
  17976.  
  17977.  
  17978.  MLM_QUERYCHANGED
  17979.  mp1 = 0L;    /* not used, must be zero */
  17980.  mp2 = 0L;    /* not used, must be zero */
  17981.  
  17982.  
  17983.  An application sends an MLM_QUERYCHANGED message to determine if the text in
  17984.  a multiple-line entry field (MLE) has changed since the last time the
  17985.  changed flag was cleared.
  17986.  
  17987.  
  17988.  Parameters
  17989.  
  17990.  This message does not use any parameters.
  17991.  
  17992.  
  17993.  Return Value
  17994.  
  17995.  The return value is TRUE if the text has changed since the last time the
  17996.  changed flag was cleared. It is FALSE if the text is unchanged or if an
  17997.  error occurs.
  17998.  
  17999.  
  18000.  Comments
  18001.  
  18002.  The changed flag can also be set or cleared by using an MLM_SETCHANGED
  18003.  message.
  18004.  
  18005.  
  18006.  See Also
  18007.  
  18008.  MLM_SETCHANGED, MLN_CHANGE, WM_CONTROL
  18009.  
  18010.  
  18011.  █    MLM_QUERYFIRSTCHAR
  18012.  ────────────────────────────────────────────────────────────────────────────
  18013.  
  18014.  
  18015.  MLM_QUERYFIRSTCHAR
  18016.  mp1 = 0L;    /* not used, must be zero */
  18017.  mp2 = 0L;    /* not used, must be zero */
  18018.  
  18019.  
  18020.  An application sends an MLM_QUERYFIRSTCHAR message to retrieve the offset
  18021.  (number of characters from the beginning of the text) of the first visible
  18022.  character in a multiple-line entry field (MLE).
  18023.  
  18024.  
  18025.  Parameters
  18026.  
  18027.  This message does not use any parameters.
  18028.  
  18029.  
  18030.  Return Value
  18031.  
  18032.  The return value is a 32-bit value (ULONG) that specifies the offset of the
  18033.  first visible character.
  18034.  
  18035.  
  18036.  See Also
  18037.  
  18038.  MLM_SETFIRSTCHAR
  18039.  
  18040.  
  18041.  █    MLM_QUERYFONT
  18042.  ────────────────────────────────────────────────────────────────────────────
  18043.  
  18044.  
  18045.  MLM_QUERYFONT
  18046.  mp1 = MPFROMP(pfattrs);    /* pointer to structure with font info. */
  18047.  mp2 = 0L;                  /* not used, must be zero               */
  18048.  
  18049.  
  18050.  An application sends an MLM_QUERYFONT message to retrieve font information
  18051.  for a multiple-line entry field (MLE).
  18052.  
  18053.  
  18054.  Parameters
  18055.  
  18056.  pfattrs  Low and high words of mp1. Points to the FATTRS structure that
  18057.  contains font information. The FATTRS structure has the following form:
  18058.  
  18059.  typedef struct _FATTRS {
  18060.      USHORT  usRecordLength;
  18061.      USHORT  fsSelection;
  18062.      LONG    lMatch;
  18063.      CHAR    szFacename[FACESIZE];
  18064.      USHORT  idRegistry;
  18065.      USHORT  usCodePage;
  18066.      LONG    lMaxBaselineExt;
  18067.      LONG    lAveCharWidth;
  18068.      USHORT  fsType;
  18069.      USHORT  fsFontUse;
  18070.  } FATTRS;
  18071.  
  18072.  
  18073.  
  18074.  
  18075.  For a full description, see  Chapter 4, "Types, Macros, Structures."
  18076.  
  18077.  
  18078.  Return Value
  18079.  
  18080.  The return value is TRUE if the system font is in use; otherwise, it is
  18081.  FALSE.
  18082.  
  18083.  
  18084.  See Also
  18085.  
  18086.  MLM_SETFONT
  18087.  
  18088.  
  18089.  
  18090.  
  18091.  █    MLM_QUERYFORMATLINELENGTH
  18092.  ────────────────────────────────────────────────────────────────────────────
  18093.  
  18094.  
  18095.  MLM_QUERYFORMATLINELENGTH
  18096.  mp1 = MPFROMLONG((LONG) lOffset); /* offset of beginning character */
  18097.  mp2 = 0L;                         /* not used, must be zero        */
  18098.  
  18099.  
  18100.  An application sends an MLM_QUERYFORMATLINELENGTH message to retrieve the
  18101.  length (in bytes) of a line in a multiple-line entry field (MLE).
  18102.  
  18103.  
  18104.  Parameters
  18105.  
  18106.  lOffset  Low and high words of mp1. Specifies the offset (number of
  18107.  characters from the beginning of the text) of the first character to count.
  18108.  If this value is -1, the current cursor position is used as the starting
  18109.  character.
  18110.  
  18111.  
  18112.  Return Value
  18113.  
  18114.  The return value is a 32-bit value (ULONG) that specifies the number of
  18115.  bytes between the specified character and the beginning of the next line. If
  18116.  the specified character is on the last line in the MLE, the number of bytes
  18117.  to the end of that line is returned.
  18118.  
  18119.  
  18120.  Comments
  18121.  
  18122.  The number of bytes returned for the end-of-line character is determined by
  18123.  the format specified by the MLM_FORMAT message. This format can be one of
  18124.  the following values:
  18125.  
  18126.  Format                            Description
  18127.  ────────────────────────────────────────────────────────────────────────────
  18128.  
  18129.  MLFIE_CFTEXT                      The end-of-line character is formatted
  18130.                                    as carriage-return/linefeed characters
  18131.                                    (2 bytes).
  18132.  
  18133.  MLFIE_NOTRANS                     The end-of-line character is formatted
  18134.                                    as a linefeed character (1 byte).
  18135.  
  18136.  MLFIE_WINFMT                      The end-of-line character for hard line
  18137.                                    breaks is formatted as
  18138.                                    carriage-return/linefeed characters (2
  18139.                                    bytes). The end-of-line character for
  18140.                                    soft line breaks (line breaks caused by
  18141.                                    word-wrapping) is formatted as
  18142.                                    carriage-return/carriage-return/linefeed
  18143.                                    characters (3 bytes).
  18144.  
  18145.  
  18146.  
  18147.  See Also
  18148.  
  18149.  MLM_FORMAT, MLM_QUERYFORMATTEXTLENGTH, MLM_QUERYLINELENGTH
  18150.  
  18151.  
  18152.  █    MLM_QUERYFORMATRECT
  18153.  ────────────────────────────────────────────────────────────────────────────
  18154.  
  18155.  
  18156.  MLM_QUERYFORMATRECT
  18157.  mp1 = MPFROMP((PMLEFORMATRECT) pmlefrmrcl); /* point to MLEFORMATRECT */
  18158.  mp2 = MPFROMP((PULONG) pflOptions);         /* point to variable      */
  18159.  
  18160.  
  18161.  An application sends an MLM_QUERYFORMATRECT message to retrieve the
  18162.  dimensions used to define the format rectangle for a multiple-line entry
  18163.  field (MLE).
  18164.  
  18165.  
  18166.  Parameters
  18167.  
  18168.  pmlefrmrcl  Low and high words of mp1. Points to the MLEFORMATRECT structure
  18169.  that receives the format-rectangle dimensions for the MLE. The MLEFORMATRECT
  18170.  structure has the following form:
  18171.  
  18172.  typedef struct _MLEFORMATRECT {
  18173.      LONG cxFormat;
  18174.      LONG cyFormat;
  18175.  } MLEFORMATRECT;
  18176.  
  18177.  
  18178.  
  18179.  
  18180.  For a full description, see Chapter 4, "Types, Macros, Structures."
  18181.  
  18182.  pflOptions  Low and high words of mp2. Points to the variable that receives
  18183.  the flags that specify how the format rectangle is to be used. A value of
  18184.  zero causes the MLE to remove any format rectangle and to ignore the
  18185.  pmlefrmrcl parameter. Otherwise, this parameter can be a combination of the
  18186.  following values:
  18187.  
  18188.  Value                             Meaning
  18189.  ────────────────────────────────────────────────────────────────────────────
  18190.  
  18191.  MLFFMTRECT_LIMITHORZ              Specifies that the text within the MLE
  18192.                                    cannot exceed the horizontal dimension
  18193.                                    specified by the pmlefrmrcl parameter.
  18194.                                    If word-wrap mode is turned on before
  18195.                                    the format rect- angle is set, lines
  18196.                                    automatically wrap to stay within the
  18197.                                    horizontal limit of the format rectangle.
  18198.                                    If word-wrap mode is turned off before
  18199.                                    the format rectangle is set, an
  18200.                                    MLN_PIXHORZOVERFLOW notification message
  18201.                                    is sent to the application whenever an
  18202.                                    operation would exceed the horizontal
  18203.                                    limit specified in the format rectangle.
  18204.  
  18205.  MLFFMTRECT_LIMITVERT              Specifies that the text within the MLE
  18206.                                    cannot exceed the vertical dimension
  18207.                                    specified by the pmlefrmrcl parameter.
  18208.                                    An MLN_PIXVERTOVERFLOW notification
  18209.                                    message is sent to the application
  18210.                                    whenever an MLE operation would cause
  18211.                                    text to exceed the vertical limit.
  18212.  
  18213.  MLFFMTRECT_MATCHWINDOW            Specifies that the format rectangle is
  18214.                                    to be kept the same size as the MLE
  18215.                                    window (minus the border or scroll bars).
  18216.  
  18217.  MLFFMTRECT_FORMATRECT             Specifies that the format rectangle is
  18218.                                    to be kept the same size as the MLE
  18219.                                    window (minus the border or scroll bars)
  18220.                                    and that text cannot exceed the size of
  18221.                                    the window. This value is equivalent to
  18222.                                    combining the MLFFMTRECT_LIMITHORZ,
  18223.                                    MLFFMTRECT_LIMITVERT, and
  18224.                                    MLFFMTRECT_MATCHWINDOW values.
  18225.  
  18226.  
  18227.  
  18228.  Return Value
  18229.  
  18230.  The return value is always FALSE.
  18231.  
  18232.  
  18233.  See Also
  18234.  
  18235.  MLM_SETFORMATRECT
  18236.  
  18237.  
  18238.  █    MLM_QUERYFORMATTEXTLENGTH
  18239.  ────────────────────────────────────────────────────────────────────────────
  18240.  
  18241.  
  18242.  MLM_QUERYFORMATTEXTLENGTH
  18243.  mp1 = MPFROMLONG((LONG) lOffset);   /* offset of starting character */
  18244.  mp2 = MPFROMLONG((LONG) cbChar);    /* characters to scan           */
  18245.  
  18246.  
  18247.  An application sends an MLM_QUERYFORMATTEXTLENGTH message to retrieve the
  18248.  length (in bytes) of a range of characters in multiple-line entry field
  18249.  (MLE).
  18250.  
  18251.  
  18252.  Parameters
  18253.  
  18254.  lOffset  Low and high words of mp1. Specifies the offset (number of
  18255.  characters from the beginning of the text) of the first character to count.
  18256.  If this parameter is set to -1, the current cursor position is used as the
  18257.  starting character.
  18258.  
  18259.  cbChar  Low and high words of mp2. Specifies the number of characters to
  18260.  scan. If this parameter is set to -1, the entire text is scanned.
  18261.  
  18262.  
  18263.  Return Value
  18264.  
  18265.  The return value is a 32-bit value (ULONG) that specifies the number of
  18266.  bytes in the specified range of characters.
  18267.  
  18268.  
  18269.  Comments
  18270.  
  18271.  The number of bytes returned for any end-of-line characters is determined by
  18272.  the format specified by the MLM_FORMAT message. This format can be one of
  18273.  the following values:
  18274.  
  18275.  Format                            Description
  18276.  ────────────────────────────────────────────────────────────────────────────
  18277.  
  18278.  MLFIE_CFTEXT                      The end-of-line character is formatted
  18279.                                    as carriage-return/ linefeed characters
  18280.                                    (2 bytes).
  18281.  
  18282.  MLFIE_NOTRANS                     The end-of-line character is formatted
  18283.                                    as a linefeed character (1 byte).
  18284.  
  18285.  MLFIE_WINFMT                      The end-of-line character for hard line
  18286.                                    breaks is formatted as
  18287.                                    carriage-return/linefeed characters (2
  18288.                                    bytes). The end-of-line character for
  18289.                                    soft line breaks (line breaks caused by
  18290.                                    word-wrapping) is formatted as
  18291.                                    carriage-return/carriage-return/linefeed
  18292.                                    characters (3 bytes).
  18293.  
  18294.  
  18295.  
  18296.  See Also
  18297.  
  18298.  MLM_FORMAT
  18299.  
  18300.  
  18301.  █    MLM_QUERYIMPORTEXPORT
  18302.  ────────────────────────────────────────────────────────────────────────────
  18303.  
  18304.  
  18305.  MLM_QUERYIMPORTEXPORT
  18306.  mp1 = MPFROMP((PBYTE FAR *) ppBuf);    /* pointer to buffer      */
  18307.  mp2 = MPFROMP((PUSHORT) pcbBuf);       /* pointer to buffer size */
  18308.  
  18309.  
  18310.  An application sends an MLM_QUERYIMPORTEXPORT message to determine the
  18311.  address and size of the buffer used by the import/export buffer of a
  18312.  multiple-line entry field (MLE). The buffer must have been set previously by
  18313.  sending an MLM_SETIMPORTEXPORT message (or the returned parameters will be
  18314.  invalid).
  18315.  
  18316.  
  18317.  Parameters
  18318.  
  18319.  ppBuf  Low and high words of mp1. Points to the variable that receives the
  18320.  address of the import/export buffer.
  18321.  
  18322.  pcbBuf  Low word of mp2. Points to the variable that receives the size of
  18323.  the buffer pointed to by ppBuf.
  18324.  
  18325.  
  18326.  Return Value
  18327.  
  18328.  The return value is always TRUE.
  18329.  
  18330.  
  18331.  Comments
  18332.  
  18333.  The import/export buffer can be used to import to and export text from the
  18334.  MLE by using the MLM_IMPORT and MLM_EXPORT messages.
  18335.  
  18336.  
  18337.  See Also
  18338.  
  18339.  MLM_EXPORT, MLM_IMPORT, MLM_SETIMPORTEXPORT
  18340.  
  18341.  
  18342.  █    MLM_QUERYLINECOUNT
  18343.  ────────────────────────────────────────────────────────────────────────────
  18344.  
  18345.  
  18346.  MLM_QUERYLINECOUNT
  18347.  mp1 = 0L;    /* not used, must be zero */
  18348.  mp2 = 0L;    /* not used, must be zero */
  18349.  
  18350.  
  18351.  An application sends an MLM_QUERYLINECOUNT message to retrieve the number of
  18352.  lines in a multiple-line entry field (MLE).
  18353.  
  18354.  
  18355.  Parameters
  18356.  
  18357.  This message does not use any parameters.
  18358.  
  18359.  
  18360.  Return Value
  18361.  
  18362.  The return value is a 32-bit value (ULONG) that specifies the number of
  18363.  lines in the MLE.
  18364.  
  18365.  
  18366.  See Also
  18367.  
  18368.  MLM_QUERYTEXTLENGTH
  18369.  
  18370.  
  18371.  █    MLM_QUERYLINELENGTH
  18372.  ────────────────────────────────────────────────────────────────────────────
  18373.  
  18374.  
  18375.  MLM_QUERYLINELENGTH
  18376.  mp1 = MPFROMLONG(lOffset);    /* beginning of count     */
  18377.  mp2 = 0L;                     /* not used, must be zero */
  18378.  
  18379.  
  18380.  An application sends an MLM_QUERYLINELENGTH message to retrieve the number
  18381.  of characters between the specified character and the beginning of the next
  18382.  line in a multiple-line entry control (MLE).
  18383.  
  18384.  
  18385.  Parameters
  18386.  
  18387.  lOffset  Low and high words of mp1. Specifies the offset (number of
  18388.  characters from the beginning of the text) of the first character to count.
  18389.  If this parameter is set to -1, the current cursor position is used as the
  18390.  starting character.
  18391.  
  18392.  
  18393.  Return Value
  18394.  
  18395.  The return value is a 32-bit value (ULONG) that specifies the number of
  18396.  characters between the specified character and the beginning of the next
  18397.  line. If the specified character is on the last line of the MLE, the number
  18398.  of characters to the end of that line is returned.
  18399.  
  18400.  
  18401.  Comments
  18402.  
  18403.  The line break at the end of the line is counted as a single character.
  18404.  
  18405.  
  18406.  See Also
  18407.  
  18408.  MLM_QUERYTEXTLENGTH
  18409.  
  18410.  
  18411.  █    MLM_QUERYREADONLY
  18412.  ────────────────────────────────────────────────────────────────────────────
  18413.  
  18414.  
  18415.  MLM_QUERYREADONLY
  18416.  mp1 = 0L;    /* not used, must be zero */
  18417.  mp2 = 0L;    /* not used, must be zero */
  18418.  
  18419.  
  18420.  An application sends an MLM_QUERYREADONLY message to determine whether the
  18421.  multiple-line entry field (MLE) is in read-only mode. While read-only mode
  18422.  is set, the user cannot change the contents of the text in the MLE.
  18423.  
  18424.  
  18425.  Parameters
  18426.  
  18427.  This message does not use any parameters.
  18428.  
  18429.  
  18430.  Return Value
  18431.  
  18432.  The return value is the read-only state of the MLE. The return value is TRUE
  18433.  when read-only mode is set.
  18434.  
  18435.  
  18436.  See Also
  18437.  
  18438.  MLM_SETREADONLY
  18439.  
  18440.  
  18441.  █    MLM_QUERYSEL
  18442.  ────────────────────────────────────────────────────────────────────────────
  18443.  
  18444.  
  18445.  MLM_QUERYSEL
  18446.  mp1 = MPFROMSHORT(usQueryMode);    /* specifies the type of query */
  18447.  mp2 = 0L;                          /* not used, must be zero      */
  18448.  
  18449.  
  18450.  An application sends an MLM_QUERYSEL message to retrieve the offsets (number
  18451.  of characters from the beginning of the text) of the characters selected in
  18452.  a multiple-line entry field (MLE).
  18453.  
  18454.  
  18455.  Parameters
  18456.  
  18457.  usQueryMode  Low word of mp1. Specifies which offset to return. This
  18458.  parameter can be one of the following values:
  18459.  
  18460.  Value                             Meaning
  18461.  ────────────────────────────────────────────────────────────────────────────
  18462.  
  18463.  MLFQS_MINMAXSEL                   Returns the offsets of the selection in
  18464.                                    a single 32-bit value. The high word
  18465.                                    contains the offset of the ending
  18466.                                    selection character, and the low word
  18467.                                    will contain the offset of the beginning
  18468.                                    character. These values are invalid if
  18469.                                    the selection contains offsets greater
  18470.                                    than 64K.
  18471.  
  18472.  MLFQS_MINSEL                      Returns the minimum (leftmost) offset of
  18473.                                    the selection.
  18474.  
  18475.  MLFQS_MAXSEL                      Returns the maximum (rightmost) offset
  18476.                                    of the selection.
  18477.  
  18478.  MLFQS_ANCHORSEL                   Returns the offset of the first selected
  18479.                                    character.
  18480.  
  18481.  MLFQS_CURSORSEL                   Returns the offset of the cursor.
  18482.  
  18483.  
  18484.  
  18485.  Return Value
  18486.  
  18487.  The return value is a 32-bit value; its meaning depends on the setting of
  18488.  the usQueryMode parameter.
  18489.  
  18490.  
  18491.  Example
  18492.  
  18493.  This example sends two MLM_QUERYSEL messages to obtain the begin- ning and
  18494.  ending points of the current selection, sends an MLM_SETIMPORTEXPORT message
  18495.  to set up the export buffer, and then sends an MLM_EXPORT message to export
  18496.  the selection into the buffer.
  18497.  
  18498.  LONG lStart, cch;
  18499.  CHAR szBuf[500];
  18500.  
  18501.  lStart = (LONG) WinSendMsg(hwndMle, MLM_QUERYSEL,
  18502.      (MPARAM) MLFQS_MINSEL, (MPARAM) 0L);
  18503.  cch = lStart - (LONG) WinSendMsg(hwndMle, MLM_QUERYSEL,
  18504.      (MPARAM) MLFQS_MAXSEL, (MPARAM) 0L);
  18505.  WinSendMsg(hwndMle, MLM_SETIMPORTEXPORT,
  18506.      (MPARAM) szBuf, (MPARAM) sizeof(szBuf));
  18507.  WinSendMsg(hwndMle, MLM_EXPORT, (MPARAM) &lStart, (MPARAM) &cch);
  18508.  
  18509.  
  18510.  
  18511.  
  18512.  
  18513.  See Also
  18514.  
  18515.  MLM_EXPORT, MLM_QUERYSELTEXT, MLM_SETIMPORTEXPORT, MLM_SETSEL
  18516.  
  18517.  
  18518.  █    MLM_QUERYSELTEXT
  18519.  ────────────────────────────────────────────────────────────────────────────
  18520.  
  18521.  
  18522.  MLM_QUERYSELTEXT
  18523.  mp1 = MPFROMP((PCH) pchBuf);   /* pointer to buffer for selection */
  18524.  mp2 = 0L;                      /* not used, must be zero          */
  18525.  
  18526.  
  18527.  An application sends an MLM_QUERYSELTEXT message to copy the selection from
  18528.  a multiple-line entry field (MLE) into the specified buffer.
  18529.  
  18530.  
  18531.  Parameters
  18532.  
  18533.  pchBuf  Low and high words of mp1. Points to the buffer that receives the
  18534.  selected text.
  18535.  
  18536.  
  18537.  Return Value
  18538.  
  18539.  The return value is a 32-bit value (ULONG) that specifies the number of
  18540.  bytes actually placed in the buffer.
  18541.  
  18542.  
  18543.  Comments
  18544.  
  18545.  The application must ensure that the selected text does not overflow the
  18546.  buffer. An application can send an MLM_QUERYSEL message to retrieve
  18547.  character offsets of the selection and then send an
  18548.  MLM_QUERYFORMATTEXTLENGTH message to determine the number of bytes the
  18549.  selected text occupies.
  18550.  
  18551.  
  18552.  See Also
  18553.  
  18554.  MLM_QUERYFORMATTEXTLENGTH, MLM_QUERYSEL
  18555.  
  18556.  
  18557.  █    MLM_QUERYTABSTOP
  18558.  ────────────────────────────────────────────────────────────────────────────
  18559.  
  18560.  
  18561.  MLM_QUERYTABSTOP
  18562.  mp1 = 0L;    /* not used, must be zero */
  18563.  mp2 = 0L;    /* not used, must be zero */
  18564.  
  18565.  
  18566.  An application sends an MLM_QUERYTABSTOP message to retrieve the interval
  18567.  (in pels) at which tab stops are set in a multiple-line entry field (MLE).
  18568.  
  18569.  
  18570.  Parameters
  18571.  
  18572.  This message does not use any parameters.
  18573.  
  18574.  
  18575.  Return Value
  18576.  
  18577.  The return value is a 16-bit value (USHORT) that specifies the tab-stop
  18578.  interval.
  18579.  
  18580.  
  18581.  See Also
  18582.  
  18583.  MLM_SETTABSTOP
  18584.  
  18585.  
  18586.  █    MLM_QUERYTEXTCOLOR
  18587.  ────────────────────────────────────────────────────────────────────────────
  18588.  
  18589.  
  18590.  MLM_QUERYTEXTCOLOR
  18591.  mp1 = 0L;    /* not used, must be zero */
  18592.  mp2 = 0L;    /* not used, must be zero */
  18593.  
  18594.  
  18595.  An application sends an MLM_QUERYTEXTCOLOR message to obtain the color of
  18596.  the text in a multiple-line entry field (MLE).
  18597.  
  18598.  
  18599.  Parameters
  18600.  
  18601.  This message does not use any parameters.
  18602.  
  18603.  
  18604.  Return Value
  18605.  
  18606.  The return value is a 32-bit value that indicates the color of the text. It
  18607.  can be one of the following values:
  18608.  
  18609.  Value                             Meaning
  18610.  ────────────────────────────────────────────────────────────────────────────
  18611.  
  18612.  CLR_FALSE                         All color planes are zeros.
  18613.  
  18614.  CLR_TRUE                          All color planes are ones.
  18615.  
  18616.  CLR_DEFAULT                       Default value; same as CLR_NEUTRAL.
  18617.  
  18618.  CLR_WHITE                         White.
  18619.  
  18620.  CLR_BLACK                         Black.
  18621.  
  18622.  CLR_BACKGROUND                    Reset color.
  18623.  
  18624.  CLR_BLUE                          Blue.
  18625.  
  18626.  CLR_RED                           Red.
  18627.  
  18628.  CLR_PINK                          Pink.
  18629.  
  18630.  CLR_GREEN                         Green.
  18631.  
  18632.  CLR_CYAN                          Cyan.
  18633.  
  18634.  CLR_YELLOW                        Yellow.
  18635.  
  18636.  CLR_NEUTRAL                       Neutral.
  18637.  
  18638.  CLR_DARKGRAY                      Dark gray.
  18639.  
  18640.  CLR_DARKBLUE                      Dark blue.
  18641.  
  18642.  CLR_DARKRED                       Dark red.
  18643.  
  18644.  CLR_DARKPINK                      Dark pink.
  18645.  
  18646.  CLR_DARKGREEN                     Dark green.
  18647.  
  18648.  CLR_DARKCYAN                      Dark cyan.
  18649.  
  18650.  CLR_BROWN                         Brown.
  18651.  
  18652.  CLR_PALEGRAY                      Light gray.
  18653.  
  18654.  
  18655.  
  18656.  See Also
  18657.  
  18658.  MLM_SETTEXTCOLOR
  18659.  
  18660.  
  18661.  █    MLM_QUERYTEXTLENGTH
  18662.  ────────────────────────────────────────────────────────────────────────────
  18663.  
  18664.  
  18665.  MLM_QUERYTEXTLENGTH
  18666.  mp1 = 0L;    /* not used, must be zero */
  18667.  mp2 = 0L;    /* not used, must be zero */
  18668.  
  18669.  
  18670.  An application sends an MLM_QUERYTEXTLENGTH message to retrieve the number
  18671.  of bytes in a multiple-line entry field (MLE).
  18672.  
  18673.  
  18674.  Parameters
  18675.  
  18676.  This message does not use any parameters.
  18677.  
  18678.  
  18679.  Return Value
  18680.  
  18681.  The return value is a 32-bit value (LONG) that specifies the number of bytes
  18682.  in the MLE. This value includes carriage-return and linefeed characters.
  18683.  
  18684.  
  18685.  See Also
  18686.  
  18687.  MLM_QUERYFORMATTEXTLENGTH
  18688.  
  18689.  
  18690.  █    MLM_QUERYTEXTLIMIT
  18691.  ────────────────────────────────────────────────────────────────────────────
  18692.  
  18693.  
  18694.  MLM_QUERYTEXTLIMIT
  18695.  mp1 = 0L;    /* not used, must be zero */
  18696.  mp2 = 0L;    /* not used, must be zero */
  18697.  
  18698.  
  18699.  An application sends an MLM_QUERYTEXTLIMIT message to retrieve the number of
  18700.  characters currently allowed in a multiple-line entry field (MLE).
  18701.  
  18702.  
  18703.  Parameters
  18704.  
  18705.  This message does not use any parameters.
  18706.  
  18707.  
  18708.  Return Value
  18709.  
  18710.  The return value is a 32-bit value (LONG) that specifies the maximum number
  18711.  of characters currently allowed in the MLE. A return value of -1 indicates
  18712.  an unlimited number of characters are allowed.
  18713.  
  18714.  
  18715.  See Also
  18716.  
  18717.  MLM_SETTEXTLIMIT
  18718.  
  18719.  
  18720.  █    MLM_QUERYUNDO
  18721.  ────────────────────────────────────────────────────────────────────────────
  18722.  
  18723.  
  18724.  MLM_QUERYUNDO
  18725.  mp1 = 0L;    /* not used, must be zero */
  18726.  mp2 = 0L;    /* not used, must be zero */
  18727.  
  18728.  
  18729.  An application sends an MLM_QUERYUNDO message to determine if a
  18730.  multiple-line entry-field (MLE) operation can be undone.
  18731.  
  18732.  
  18733.  Parameters
  18734.  
  18735.  This message does not use any parameters.
  18736.  
  18737.  
  18738.  Return Value
  18739.  
  18740.  The return value is a 32-bit value that indicates whether an MLE operation
  18741.  can be undone and, if so, which message can be undone. The low word contains
  18742.  TRUE if the message can be undone or FALSE if the message was just undone.
  18743.  The high word contains the message, or it contains zero if no message is
  18744.  available to be undone. The following messages can be returned:
  18745.  
  18746.  Message                           Description
  18747.  ────────────────────────────────────────────────────────────────────────────
  18748.  
  18749.  MLM_CLEAR                         Indicates that the last MLM_CLEAR or
  18750.                                    MLM_DELETE message can be undone.
  18751.  
  18752.  MLM_CUT                           Indicates that the last MLM_CUT message
  18753.                                    can be undone.
  18754.  
  18755.  MLM_INSERT                        Indicates that the last MLM_INSERT
  18756.                                    message can be undone. ,
  18757.  
  18758.  MLM_PASTE                         Indicates that the last MLM_PASTE
  18759.                                    message can be undone.
  18760.  
  18761.  MLM_SETFONT                       Indicates that the last MLM_SETFONT
  18762.                                    message can be undone.
  18763.  
  18764.  MLM_SETTEXTCOLOR                  Indicates the last MLM_SETBACKCOLOR or
  18765.                                    MLM_SETTEXTCOLOR message can be undone.
  18766.  
  18767.  WM_CHAR                           Indicates that the last character
  18768.                                    entered by the user can be undone.
  18769.  
  18770.  
  18771.  
  18772.  See Also
  18773.  
  18774.  MLM_RESETUNDO, MLM_UNDO
  18775.  
  18776.  
  18777.  █    MLM_QUERYWRAP
  18778.  ────────────────────────────────────────────────────────────────────────────
  18779.  
  18780.  
  18781.  MLM_QUERYWRAP
  18782.  mp1 = 0L;    /* not used, must be zero */
  18783.  mp2 = 0L;    /* not used, must be zero */
  18784.  
  18785.  
  18786.  An application sends an MLM_QUERYWRAP message to retrieve the current state
  18787.  of word-wrapping in a multiple-line entry field (MLE).
  18788.  
  18789.  
  18790.  Parameters
  18791.  
  18792.  This message does not use any parameters.
  18793.  
  18794.  
  18795.  Return Value
  18796.  
  18797.  The return value is TRUE if word-wrapping is currently set. It is FALSE if
  18798.  word-wrapping is not set.
  18799.  
  18800.  
  18801.  See Also
  18802.  
  18803.  MLM_SETWRAP
  18804.  
  18805.  
  18806.  █    MLM_RESETUNDO
  18807.  ────────────────────────────────────────────────────────────────────────────
  18808.  
  18809.  
  18810.  MLM_RESETUNDO
  18811.  mp1 = 0L;    /* not used, must be zero */
  18812.  mp2 = 0L;    /* not used, must be zero */
  18813.  
  18814.  
  18815.  An application sends an MLM_RESETUNDO message to reset (clear) the undo flag
  18816.  of a multiple-line entry field (MLE). The undo flag is set whenever an
  18817.  operation within the MLE can be undone.
  18818.  
  18819.  
  18820.  Parameters
  18821.  
  18822.  This message does not use any parameters.
  18823.  
  18824.  
  18825.  Return Value
  18826.  
  18827.  The return value is TRUE if the MLE undo flag is cleared as a result of this
  18828.  message. Otherwise, the return value is FALSE, indicating that the undo flag
  18829.  was already cleared.
  18830.  
  18831.  
  18832.  See Also
  18833.  
  18834.  MLM_QUERYUNDO, MLM_UNDO
  18835.  
  18836.  
  18837.  █    MLM_SEARCH
  18838.  ────────────────────────────────────────────────────────────────────────────
  18839.  
  18840.  
  18841.  MLM_SEARCH
  18842.  mp1 = MPFROMLONG(ulStyle);  /* search style                          */
  18843.  mp2 = MPFROMP(pmlesearch);  /* address of structure with search data */
  18844.  
  18845.  
  18846.  An application sends an MLM_SEARCH message to search for (and optionally
  18847.  replace) text within a multiple-line entry field (MLE).
  18848.  
  18849.  
  18850.  Parameters
  18851.  
  18852.  ulStyle  Low and high words of mp1. Specifies the style of the search. This
  18853.  parameter can be any combination of the following values:
  18854.  
  18855.  Value                             Meaning
  18856.  ────────────────────────────────────────────────────────────────────────────
  18857.  
  18858.  MLFSEARCH_CASESENSITIVE           Specifies that the search is
  18859.                                    case-sensitive.
  18860.  
  18861.  MLFSEARCH_SELECTMATCH             Specifies that if the text is found, it
  18862.                                    should be highlighted and scrolled into
  18863.                                    view (if necessary). This is identical
  18864.                                    to sending the MLM_SETSEL message.
  18865.  
  18866.  MLFSEARCH_CHANGEALL               Specifies that all text found is to be
  18867.                                    replaced by the text in the pchReplace
  18868.                                    field of the MLE_SEARCHDATA structure.
  18869.  
  18870.  
  18871.  
  18872.  pmlesearch  Low and high words of mp2. Points to the MLE_SEARCHDATA
  18873.  structure that contains the search data. The MLE_SEARCHDATA structure has
  18874.  the following form:
  18875.  
  18876.  typedef struct _MLE_SEARCHDATA {
  18877.     USHORT cb;
  18878.     PCHAR  pchFind;
  18879.     PCHAR  pchReplace;
  18880.     SHORT  cchFind;
  18881.     SHORT  cchReplace;
  18882.     IPT    iptStart;
  18883.     IPT    iptStop;
  18884.     USHORT cchFound;
  18885.  } MLE_SEARCHDATA;
  18886.  
  18887.  
  18888.  
  18889.  
  18890.  For a full description, see Chapter 4, "Types, Macros, Structures."
  18891.  
  18892.  
  18893.  Return Value
  18894.  
  18895.  The return value is TRUE if the search is successful, or it is FALSE,
  18896.  indicating that the search string was not found.
  18897.  
  18898.  
  18899.  Comments
  18900.  
  18901.  If the MLFSEARCH_CHANGEALL flag is not set and a match is found, the
  18902.  iptStart field of the MLE_SEARCHDATA structure is set to the offset (number
  18903.  of characters from the beginning of the text) of the first character that
  18904.  matches the search string. The cchFound field is set to the number of
  18905.  characters that match the search string. The current cursor position is not
  18906.  changed unless the MLFSEARCH_SELECTMATCH flag is set.
  18907.  
  18908.  While the MLE is searching, it periodically sends an MLN_SEARCHPAUSE message
  18909.  that contains the current position of the search. You can terminate the
  18910.  search by returning TRUE to the MLN_SEARCHPAUSE notification message.
  18911.  
  18912.  
  18913.  Example
  18914.  
  18915.  This example searches for all occurrences of the word bonnie and replaces it
  18916.  with the word jeannette:
  18917.  
  18918.  MLE_SEARCHDATA search;
  18919.  search.cb = sizeof(search);
  18920.  search.pchFind = "bonnie";
  18921.  search.pchReplace = "jeannette";
  18922.  search.cchFind = 6;
  18923.  search.cchReplace = 9;
  18924.  search.iptStart = 0;   /* from the beginning of the text */
  18925.  search.iptStop = -1;   /* to the end of the text         */
  18926.  WinSendMsg(hwndMle, MLM_SEARCH, MLFSEARCH_CHANGEALL, (MPARAM) &search);
  18927.  
  18928.  
  18929.  
  18930.  
  18931.  
  18932.  See Also
  18933.  
  18934.  MLM_SETSEL, MLN_SEARCHPAUSE, WM_CONTROL
  18935.  
  18936.  
  18937.  
  18938.  
  18939.  █    MLM_SETBACKCOLOR
  18940.  ────────────────────────────────────────────────────────────────────────────
  18941.  
  18942.  
  18943.  MLM_SETBACKCOLOR
  18944.  mp1 = MPFROMLONG((COLOR) clr);    /* color                  */
  18945.  mp2 = 0L;                         /* not used, must be zero */
  18946.  
  18947.  
  18948.  An application sends an MLM_SETBACKCOLOR message to set the background color
  18949.  of a multiple-line entry field (MLE).
  18950.  
  18951.  
  18952.  Parameters
  18953.  
  18954.  clr  Specifies the color. This parameter can be one of the following values:
  18955.  
  18956.  
  18957.  Value                             Meaning
  18958.  ────────────────────────────────────────────────────────────────────────────
  18959.  
  18960.  CLR_FALSE                         All color planes are zeros.
  18961.  
  18962.  CLR_TRUE                          All color planes are ones.
  18963.  
  18964.  CLR_DEFAULT                       Default value; same as CLR_NEUTRAL.
  18965.  
  18966.  CLR_WHITE                         White.
  18967.  
  18968.  CLR_BLACK                         Black.
  18969.  
  18970.  CLR_BACKGROUND                    Reset color.
  18971.  
  18972.  CLR_BLUE                          Blue.
  18973.  
  18974.  CLR_RED                           Red.
  18975.  
  18976.  CLR_PINK                          Pink.
  18977.  
  18978.  CLR_GREEN                         Green.
  18979.  
  18980.  CLR_CYAN                          Cyan.
  18981.  
  18982.  CLR_YELLOW                        Yellow.
  18983.  
  18984.  CLR_NEUTRAL                       Neutral.
  18985.  
  18986.  CLR_DARKGRAY                      Dark gray.
  18987.  
  18988.  CLR_DARKBLUE                      Dark blue.
  18989.  
  18990.  CLR_DARKRED                       Dark red.
  18991.  
  18992.  CLR_DARKPINK                      Dark pink.
  18993.  
  18994.  CLR_DARKGREEN                     Dark green.
  18995.  
  18996.  CLR_DARKCYAN                      Dark cyan.
  18997.  
  18998.  CLR_BROWN                         Brown.
  18999.  
  19000.  CLR_PALEGRAY                      Light gray.
  19001.  
  19002.  
  19003.  
  19004.  Return Value
  19005.  
  19006.  The return value is the previous color of the background.
  19007.  
  19008.  
  19009.  See Also
  19010.  
  19011.  MLM_QUERYBACKCOLOR, MLM_SETTEXTCOLOR
  19012.  
  19013.  
  19014.  █    MLM_SETCHANGED
  19015.  ────────────────────────────────────────────────────────────────────────────
  19016.  
  19017.  
  19018.  MLM_SETCHANGED
  19019.  mp1 = MPFROMSHORT((BOOL) fChanged);    /* changed flag           */
  19020.  mp2 = 0L;                              /* not used, must be zero */
  19021.  
  19022.  
  19023.  An application sends an MLM_SETCHANGED message to set or clear the
  19024.  multiple-line entry field (MLE) changed flag.
  19025.  
  19026.  
  19027.  Parameters
  19028.  
  19029.  fChanged  Low word of mp1. Specifies whether to set or clear the changed
  19030.  flag. A value of TRUE sets the changed flag.
  19031.  
  19032.  
  19033.  Return Value
  19034.  
  19035.  The return value is the previous state of the MLE changed flag.
  19036.  
  19037.  
  19038.  See Also
  19039.  
  19040.  MLM_QUERYCHANGED, MLN_CHANGE, WM_CONTROL
  19041.  
  19042.  
  19043.  █    MLM_SETFIRSTCHAR
  19044.  ────────────────────────────────────────────────────────────────────────────
  19045.  
  19046.  
  19047.  MLM_SETFIRSTCHAR
  19048.  mp1 = MPFROMLONG(lOffChar);    /* insertion point        */
  19049.  mp2 = 0L;                      /* not used, must be zero */
  19050.  
  19051.  
  19052.  An application sends an MLM_SETFIRSTCHAR message to specify the first
  19053.  visible character in a multiple-line entry field (MLE). The MLE scrolls the
  19054.  text vertically and horizontally as needed to place the character in the
  19055.  upper-left corner of the MLE window.
  19056.  
  19057.  
  19058.  Parameters
  19059.  
  19060.  lOffChar  Low and high words of mp1. Specifies the offset (number of
  19061.  characters from the beginning of the text) of the character to be placed in
  19062.  the upper-left corner of the MLE window.
  19063.  
  19064.  
  19065.  Return Value
  19066.  
  19067.  The return value is always TRUE.
  19068.  
  19069.  
  19070.  Comments
  19071.  
  19072.  If the value specified by the lOffChar parameter is greater than the total
  19073.  number of characters in the MLE, the first visible character is set one
  19074.  beyond the last character in the MLE.
  19075.  
  19076.  
  19077.  See Also
  19078.  
  19079.  MLM_QUERYFIRSTCHAR
  19080.  
  19081.  
  19082.  █    MLM_SETFONT
  19083.  ────────────────────────────────────────────────────────────────────────────
  19084.  
  19085.  
  19086.  MLM_SETFONT
  19087.  mp1 = MPFROMP(pfattrs);    /* pointer to structure with font info. */
  19088.  mp2 = 0L;                  /* not used, must be zero               */
  19089.  
  19090.  
  19091.  An application sends an MLM_SETFONT message to set the font for a
  19092.  multiple-line entry field (MLE).
  19093.  
  19094.  
  19095.  Parameters
  19096.  
  19097.  pfattrs  Low and high words of mp1. Points to the FATTRS structure that
  19098.  contains the font information. The FATTRS structure has the following form:
  19099.  
  19100.  typedef struct _FATTRS {
  19101.      USHORT  usRecordLength;
  19102.      USHORT  fsSelection;
  19103.      LONG    lMatch;
  19104.      CHAR    szFacename[FACESIZE];
  19105.      USHORT  idRegistry;
  19106.      USHORT  usCodePage;
  19107.      LONG    lMaxBaselineExt;
  19108.      LONG    lAveCharWidth;
  19109.      USHORT  fsType;
  19110.      USHORT  fsFontUse;
  19111.  } FATTRS;
  19112.  
  19113.  
  19114.  
  19115.  
  19116.  For a full description, see  Chapter 4, "Types, Macros, Structures."
  19117.  
  19118.  
  19119.  Return Value
  19120.  
  19121.  The return value is TRUE if the font is successfully set or FALSE if an
  19122.  error occurs.
  19123.  
  19124.  
  19125.  Example
  19126.  
  19127.  This example retrieves the current font information, changes it to italic,
  19128.  and sets it using the MLM_SETFONT message:
  19129.  
  19130.  FATTRS fat;
  19131.  fat.usRecordLength = sizeof(FATTRS);
  19132.  WinSendMsg(hwndMle, MLM_QUERYFONT, (MPARAM) &fat, (MPARAM) 0L);
  19133.  fat.fsSelection = FATTR_SEL_ITALIC;
  19134.  WinSendMsg(hwndMle, MLM_SETFONT, (MPARAM) &fat, (MPARAM) 0);
  19135.  
  19136.  
  19137.  
  19138.  
  19139.  
  19140.  See Also
  19141.  
  19142.  MLM_QUERYFONT
  19143.  
  19144.  
  19145.  
  19146.  
  19147.  █    MLM_SETFORMATRECT
  19148.  ────────────────────────────────────────────────────────────────────────────
  19149.  
  19150.  
  19151.  MLM_SETFORMATRECT
  19152.  mp1 = MPFROMP((PMLEFORMATRECT) pmlefrmrcl); /* point to format rect. */
  19153.  mp2 = MPFROMLONG((ULONG) flOptions);        /* options               */
  19154.  
  19155.  
  19156.  An application sends an MLM_SETFORMATRECT message to set a format rectangle
  19157.  in a multiple-line entry field (MLE). The format rectangle can be used to
  19158.  limit the insertion of text within the MLE window.
  19159.  
  19160.  
  19161.  Parameters
  19162.  
  19163.  pmlefrmrcl  Low and high words of mp1. Points to the MLEFORMATRECT structure
  19164.  that contains the format-rectangle dimensions. If this parameter is NULL,
  19165.  the current MLE-window dimensions (minus the border or scroll bars) is used.
  19166.  The MLEFORMATRECT structure has the following form:
  19167.  
  19168.  typedef struct _MLEFORMATRECT {
  19169.      LONG cxFormat;
  19170.      LONG cyFormat;
  19171.  } MLEFORMATRECT;
  19172.  
  19173.  
  19174.  
  19175.  
  19176.  For a full description, see  Chapter 4, "Types, Macros, Structures."
  19177.  
  19178.  flOptions  Low and high words of mp2. Specifies how the format rectangle is
  19179.  to be used. A value of zero causes the MLE to remove any format rectangle
  19180.  and to ignore the pmlefrmrcl parameter. Otherwise, this parameter can be a
  19181.  combination of the following values:
  19182.  
  19183.  Value                             Meaning
  19184.  ────────────────────────────────────────────────────────────────────────────
  19185.  
  19186.  MLFFMTRECT_LIMITHORZ              Specifies that the text within the MLE
  19187.                                    cannot exceed the horizontal dimension
  19188.                                    specified by the pmlefrmrcl parameter.
  19189.                                    If word-wrap mode is turned on before
  19190.                                    the format rect- angle is set, lines
  19191.                                    automatically wrap to stay within the
  19192.                                    horizontal limit of the format rectangle.
  19193.                                    If word-wrap mode is turned off before
  19194.                                    the format rectangle is set, an
  19195.                                    MLN_PIXHORZOVERFLOW notification message
  19196.                                    is sent to the application whenever an
  19197.                                    operation would exceed the horizontal
  19198.                                    limit specified in the format rectangle.
  19199.  
  19200.  MLFFMTRECT_LIMITVERT              Specifies that the text within the MLE
  19201.                                    cannot exceed the vertical dimension
  19202.                                    specified by the pmlefrmrcl parameter.
  19203.                                    When an MLE operation would cause text
  19204.                                    to exceed the vertical limit, an
  19205.                                    MLN_PIXVERTOVERFLOW notification message
  19206.                                    is sent to the application.
  19207.  
  19208.  MLFFMTRECT_MATCHWINDOW            Specifies that the format rectangle is
  19209.                                    to be kept the same size as the MLE
  19210.                                    window (minus the border or scroll bars).
  19211.  
  19212.  MLFFMTRECT_FORMATRECT             Specifies that the format rectangle is
  19213.                                    to be kept the same size as the MLE
  19214.                                    window (minus the border or scroll bars)
  19215.                                    and that text cannot exceed the size of
  19216.                                    the window. This value is equivalent to
  19217.                                    combining the MLFFMTRECT_LIMITHORZ,
  19218.                                    MLFFMTRECT_LIMITVERT, and
  19219.                                    MLFFMTRECT_MATCHWINDOW values.
  19220.  
  19221.  
  19222.  
  19223.  Return Value
  19224.  
  19225.  The return value is TRUE if the text fits within the new format-rectangle
  19226.  dimensions. Otherwise, it is FALSE, indicating that the text does not fit
  19227.  and that the format rectangle is not set.
  19228.  
  19229.  
  19230.  Comments
  19231.  
  19232.  Whenever an insertion would cause the text to be too long for the MLE, the
  19233.  MLN_PIXVERTOVERFLOW or MLN_PIXHORZOVERFLOW notification message is sent.
  19234.  
  19235.  
  19236.  See Also
  19237.  
  19238.  MLM_QUERYFORMATRECT, MLN_PIXHORZOVERFLOW, MLN_PIXVERTOVERFLOW, WM_CONTROL
  19239.  
  19240.  
  19241.  █    MLM_SETIMPORTEXPORT
  19242.  ────────────────────────────────────────────────────────────────────────────
  19243.  
  19244.  
  19245.  MLM_SETIMPORTEXPORT
  19246.  mp1 = MPFROMP((PBYTE) pBuf);          /* pointer to buffer */
  19247.  mp2 = MPFROMSHORT((USHORT) cbBuf);    /* buffer size       */
  19248.  
  19249.  
  19250.  An application sends an MLM_SETIMPORTEXPORT message to set the transfer
  19251.  buffer for a multiple-line entry field (MLE).
  19252.  
  19253.  
  19254.  Parameters
  19255.  
  19256.  pBuf  Low and high words of mp1. Points to the buffer to be used by the
  19257.  MLM_IMPORT, MLM_EXPORT, and MLM_SEARCH messages.
  19258.  
  19259.  cbBuf  Low word of mp2. Specifies the size (in bytes) of the buffer pointed
  19260.  to by the pBuf parameter. The largest size that can be specified is 65,535.
  19261.  
  19262.  
  19263.  Return Value
  19264.  
  19265.  The return value is always TRUE.
  19266.  
  19267.  
  19268.  See Also
  19269.  
  19270.  MLM_EXPORT, MLM_IMPORT
  19271.  
  19272.  
  19273.  █    MLM_SETREADONLY
  19274.  ────────────────────────────────────────────────────────────────────────────
  19275.  
  19276.  
  19277.  MLM_SETREADONLY
  19278.  mp1 = MPFROMSHORT(fReadOnly);    /* read-only flag         */
  19279.  mp2 = 0L;                        /* not used, must be zero */
  19280.  
  19281.  
  19282.  An application sends an MLM_SETREADONLY message to set the read-only state
  19283.  of a multiple-line entry field (MLE). While the read-only state is set, the
  19284.  user cannot change the contents of the MLE text.
  19285.  
  19286.  
  19287.  Parameters
  19288.  
  19289.  fReadOnly  Low word of mp1. Specifies the read-only state of the MLE. A
  19290.  value of TRUE sets the read-only state.
  19291.  
  19292.  
  19293.  Return Value
  19294.  
  19295.  The return value is the previous value of the read-only state. If the return
  19296.  value is zero, the read-only state was turned off. If the return value is
  19297.  nonzero, the read-only state was turned on.
  19298.  
  19299.  
  19300.  See Also
  19301.  
  19302.  MLM_QUERYREADONLY
  19303.  
  19304.  
  19305.  █    MLM_SETSEL
  19306.  ────────────────────────────────────────────────────────────────────────────
  19307.  
  19308.  
  19309.  MLM_SETSEL
  19310.  mp1 = MPFROMLONG(lOffsetBegin);    /* offset of beginning character */
  19311.  mp2 = MPFROMLONG(lOffsetEnd);      /* offset of ending character    */
  19312.  
  19313.  
  19314.  An application sends an MLM_SETSEL message to select an area of text within
  19315.  a multiple-line entry field (MLE).
  19316.  
  19317.  
  19318.  Parameters
  19319.  
  19320.  lOffsetBegin  Low and high words of mp1. Specifies the offset (number of
  19321.  characters from the beginning of the text) of the first character. If this
  19322.  parameter is set to -1, the current cursor position is used.
  19323.  
  19324.  lOffsetEnd  Low and high words of mp2. Specifies the offset of the character
  19325.  just beyond the selection, where the cursor is to be placed. If this
  19326.  parameter is set to -1, the current cursor position is used.
  19327.  
  19328.  
  19329.  Return Value
  19330.  
  19331.  The return value is always TRUE.
  19332.  
  19333.  
  19334.  Comments
  19335.  
  19336.  The MLE scrolls the text vertically and horizontally as needed to make the
  19337.  selection visible.
  19338.  
  19339.  If the lOffsetEnd parameter is greater than the lOffsetBegin parameter, the
  19340.  cursor is placed to the right of the selected text. If lOffsetEnd is less
  19341.  than lOffsetBegin, the cursor is placed to the left of the selected text.
  19342.  
  19343.  Character offsets are zero-based. Therefore, the first character has an
  19344.  offset of zero.
  19345.  
  19346.  
  19347.  Example
  19348.  
  19349.  This example highlights the second, third, and fourth characters of the
  19350.  text, and places the cursor to the right of the fourth character.
  19351.  
  19352.  WinSendMsg(hwndMle, MLM_SETSEL, (MPARAM) 1L, (MPARAM) 4L);
  19353.  
  19354.  
  19355.  
  19356.  
  19357.  
  19358.  See Also
  19359.  
  19360.  MLM_QUERYSEL
  19361.  
  19362.  
  19363.  █    MLM_SETTABSTOP
  19364.  ────────────────────────────────────────────────────────────────────────────
  19365.  
  19366.  
  19367.  MLM_SETTABSTOP
  19368.  mp1 = MPFROMSHORT((USHORT) usTabInterval); /* tab-stop interval      */
  19369.  mp2 = 0L;                                  /* not used, must be zero */
  19370.  
  19371.  
  19372.  An application sends an MLM_SETTABSTOP message to set the interval (in pels)
  19373.  at which tab stops are placed in a multiple-line entry field (MLE).
  19374.  
  19375.  
  19376.  Parameters
  19377.  
  19378.  usTabInterval  Low word of mp1. Specifies the interval (in pels) for tab
  19379.  stops.
  19380.  
  19381.  
  19382.  Return Value
  19383.  
  19384.  The return value is a 16-bit value (USHORT) that specifies the tab-stop
  19385.  interval.
  19386.  
  19387.  
  19388.  See Also
  19389.  
  19390.  MLM_QUERYTABSTOP
  19391.  
  19392.  
  19393.  █    MLM_SETTEXTCOLOR
  19394.  ────────────────────────────────────────────────────────────────────────────
  19395.  
  19396.  
  19397.  MLM_SETTEXTCOLOR
  19398.  mp1 = MPFROMLONG((COLOR) clr);    /* color                  */
  19399.  mp2 = 0L;                         /* not used, must be zero */
  19400.  
  19401.  
  19402.  An application sends an MLM_SETTEXTCOLOR message to set the text color of a
  19403.  multiple-line entry field (MLE).
  19404.  
  19405.  
  19406.  Parameters
  19407.  
  19408.  clr  Specifies the color. This parameter can be one of the following values:
  19409.  
  19410.  
  19411.  Value                             Meaning
  19412.  ────────────────────────────────────────────────────────────────────────────
  19413.  
  19414.  CLR_FALSE                         All color planes are zeros.
  19415.  
  19416.  CLR_TRUE                          All color planes are ones.
  19417.  
  19418.  CLR_DEFAULT                       Default value; same as CLR_NEUTRAL.
  19419.  
  19420.  CLR_WHITE                         White.
  19421.  
  19422.  CLR_BLACK                         Black.
  19423.  
  19424.  CLR_BACKGROUND                    Reset color.
  19425.  
  19426.  CLR_BLUE                          Blue.
  19427.  
  19428.  CLR_RED                           Red.
  19429.  
  19430.  CLR_PINK                          Pink.
  19431.  
  19432.  CLR_GREEN                         Green.
  19433.  
  19434.  CLR_CYAN                          Cyan.
  19435.  
  19436.  CLR_YELLOW                        Yellow.
  19437.  
  19438.  CLR_NEUTRAL                       Neutral.
  19439.  
  19440.  CLR_DARKGRAY                      Dark gray.
  19441.  
  19442.  CLR_DARKBLUE                      Dark blue.
  19443.  
  19444.  CLR_DARKRED                       Dark red.
  19445.  
  19446.  CLR_DARKPINK                      Dark pink.
  19447.  
  19448.  CLR_DARKGREEN                     Dark green.
  19449.  
  19450.  CLR_DARKCYAN                      Dark cyan.
  19451.  
  19452.  CLR_BROWN                         Brown.
  19453.  
  19454.  CLR_PALEGRAY                      Light gray.
  19455.  
  19456.  
  19457.  
  19458.  Return Value
  19459.  
  19460.  The return value is the previous color of the text.
  19461.  
  19462.  
  19463.  See Also
  19464.  
  19465.  MLM_QUERYTEXTCOLOR, MLM_SETBACKCOLOR
  19466.  
  19467.  
  19468.  █    MLM_SETTEXTLIMIT
  19469.  ────────────────────────────────────────────────────────────────────────────
  19470.  
  19471.  
  19472.  MLM_SETTEXTLIMIT
  19473.  mp1 = MPFROMLONG(cch);    /* maximum number of characters */
  19474.  mp2 = 0L;                 /* not used, must be zero       */
  19475.  
  19476.  
  19477.  An application sends an MLM_SETTEXTLIMIT message to set the text size of a
  19478.  multiple-line entry field (MLE). The MLE does not accept any characters
  19479.  beyond this limit.
  19480.  
  19481.  
  19482.  Parameters
  19483.  
  19484.  cch  Low and high words of mp1. Specifies the maximum number of characters
  19485.  allowed in the MLE. A value of -1 specifies unlimited text is allowed.
  19486.  
  19487.  
  19488.  Return Value
  19489.  
  19490.  The return value is zero if the current MLE text is less than the new limit.
  19491.  Otherwise, the return value is the number of characters that exceed the
  19492.  specified limit, and the limit is not set.
  19493.  
  19494.  
  19495.  Comments
  19496.  
  19497.  If the user inserts more text than the specified maximum for the MLE, an
  19498.  MLN_TEXTOVERFLOW message is sent. If the application inserts more text than
  19499.  the specified maximum, an MLN_OVERFLOW notification message is sent.
  19500.  
  19501.  
  19502.  See Also
  19503.  
  19504.  MLM_QUERYTEXTLIMIT, MLN_OVERFLOW, MLN_TEXTOVERFLOW, WM_CONTROL
  19505.  
  19506.  
  19507.  █    MLM_SETWRAP
  19508.  ────────────────────────────────────────────────────────────────────────────
  19509.  
  19510.  
  19511.  MLM_SETWRAP
  19512.  mp1 = MPFROMSHORT(fWrap);    /* word-wrap flag         */
  19513.  mp2 = 0L;                    /* not used, must be zero */
  19514.  
  19515.  
  19516.  An application sends an MLM_SETWRAP message to set word-wrap mode in a
  19517.  multiple-line entry field (MLE).
  19518.  
  19519.  
  19520.  Parameters
  19521.  
  19522.  fWrap  Low word of mp1. Specifies whether to turn word-wrap mode on or off.
  19523.  If this parameter is TRUE, word-wrapping is turned on. If it is FALSE,
  19524.  word-wrapping is turned off.
  19525.  
  19526.  
  19527.  Return Value
  19528.  
  19529.  The return value is TRUE if word-wrap mode is set as a result of this
  19530.  message. Otherwise, the return value is FALSE, indicating that the word-wrap
  19531.  mode cannot be changed.
  19532.  
  19533.  
  19534.  Comments
  19535.  
  19536.  Word-wrap mode affects only the visual display of the text. Line breaks
  19537.  inserted by the user are not affected.
  19538.  
  19539.  Word-wrap mode cannot be turned off while the text exceeds the format
  19540.  rectangle specified in the MLM_SETFORMATRECT message. Word-wrap mode cannot
  19541.  be turned on if the result of word-wrapping would cause the text to exceed
  19542.  the format rectangle specified in the MLM_SETFORMATRECT message.
  19543.  
  19544.  
  19545.  See Also
  19546.  
  19547.  MLM_QUERYWRAP, MLM_SETFORMATRECT
  19548.  
  19549.  
  19550.  █    MLM_UNDO
  19551.  ────────────────────────────────────────────────────────────────────────────
  19552.  
  19553.  
  19554.  MLM_UNDO
  19555.  mp1 = 0L;    /* not used, must be zero */
  19556.  mp2 = 0L;    /* not used, must be zero */
  19557.  
  19558.  
  19559.  An application sends an MLM_UNDO message to undo a multiple-line entry-field
  19560.  (MLE) operation.
  19561.  
  19562.  
  19563.  Parameters
  19564.  
  19565.  This message does not use any parameters.
  19566.  
  19567.  
  19568.  Return Value
  19569.  
  19570.  The return value is TRUE if an MLE operation is undone.
  19571.  
  19572.  
  19573.  Comments
  19574.  
  19575.  Only the following MLE operations can be undone:
  19576.  
  19577.       MLM_CLEAR
  19578.       MLM_CUT
  19579.       MLM_DELETE
  19580.       MLM_INSERT
  19581.       MLM_PASTE
  19582.       MLM_SETBACKCOLOR
  19583.       MLM_SETFONT
  19584.       MLM_SETTEXTCOLOR
  19585.       MLM_UNDO
  19586.       WM_CHAR
  19587.  
  19588.  
  19589.  
  19590.  
  19591.  If an MLM_UNDO message is sent when the undo flag has been cleared, it
  19592.  reverses the previous undo operation.
  19593.  
  19594.  
  19595.  See Also
  19596.  
  19597.  MLM_QUERYUNDO, MLM_RESETUNDO
  19598.  
  19599.  
  19600.  █    MLN_CHANGE
  19601.  ────────────────────────────────────────────────────────────────────────────
  19602.  
  19603.  
  19604.  WM_CONTROL
  19605.  id = (USHORT) SHORT1FROMMP(mp1);    /* MLE-window ID */
  19606.  usNotifyCode = MLN_CHANGE;
  19607.  
  19608.  
  19609.  The MLN_CHANGE notification message is sent whenever the text in a
  19610.  multiple-line entry field (MLE) changes.
  19611.  
  19612.  
  19613.  Parameters
  19614.  
  19615.  id  Low word of mp1. Identifies the MLE window.
  19616.  
  19617.  usNotifyCode  High word of mp1. Set to MLN_CHANGE.
  19618.  
  19619.  
  19620.  See Also
  19621.  
  19622.  MLM_QUERYCHANGED, MLM_SETCHANGED, WM_CONTROL
  19623.  
  19624.  
  19625.  █    MLN_CLPBDFAIL
  19626.  ────────────────────────────────────────────────────────────────────────────
  19627.  
  19628.  
  19629.  WM_CONTROL
  19630.  id = (USHORT) SHORT1FROMMP(mp1);        /* MLE-window ID */
  19631.  usNotifyCode = MLN_CLPBDFAIL;
  19632.  sError = (USHORT) SHORT1FROMMP(mp2);    /* error code    */
  19633.  
  19634.  
  19635.  The MLN_CLPBDFAIL notification message is sent if the clipboard is unable to
  19636.  receive the text sent to it by a multiple-line entry field (MLE).
  19637.  
  19638.  
  19639.  Parameters
  19640.  
  19641.  id  Low word of mp1. Identifies the MLE window.
  19642.  
  19643.  usNotifyCode  High word of mp1. Set to MLN_CLPBDFAIL.
  19644.  
  19645.  sError  Specifies the error that occurred. This parameter can be one of the
  19646.  following error values:
  19647.  
  19648.  Value                             Meaning
  19649.  ────────────────────────────────────────────────────────────────────────────
  19650.  
  19651.  MLFCLPBD_TOOMUCHTEXT              Specifies that the amount of text
  19652.                                    exceeds the capacity of the clipboard.
  19653.  
  19654.  MLFCLPBD_ERROR                    Specifies an unknown clipboard error.
  19655.  
  19656.  
  19657.  
  19658.  See Also
  19659.  
  19660.  MLM_COPY, MLM_CUT, WM_CONTROL
  19661.  
  19662.  
  19663.  █    MLN_HSCROLL
  19664.  ────────────────────────────────────────────────────────────────────────────
  19665.  
  19666.  
  19667.  WM_CONTROL
  19668.  id = (USHORT) SHORT1FROMMP(mp1);      /* scroll-bar window ID */
  19669.  usNotifyCode = MLN_HSCROLL;
  19670.  sPos = (USHORT) SHORT1FROMMP(mp2);    /* slider position      */
  19671.  
  19672.  
  19673.  The MLN_HSCROLL notification message is sent to the owner of the
  19674.  multiple-line entry field (MLE) window when a horizontal scroll event
  19675.  occurs.
  19676.  
  19677.  
  19678.  Parameters
  19679.  
  19680.  id  Low word of mp1. Identifies the MLE window.
  19681.  
  19682.  usNotifyCode  High word of mp1. Set to MLN_HSCROLL.
  19683.  
  19684.  sPos  Low word of mp2. Specifies the number of pels of text (nonvisible) to
  19685.  the left of the window.
  19686.  
  19687.  
  19688.  Return Value
  19689.  
  19690.  An application should return zero if it processes this message.
  19691.  
  19692.  
  19693.  See Also
  19694.  
  19695.  MLN_VSCROLL, WM_CONTROL
  19696.  
  19697.  
  19698.  █    MLN_KILLFOCUS
  19699.  ────────────────────────────────────────────────────────────────────────────
  19700.  
  19701.  
  19702.  WM_CONTROL
  19703.  id = (USHORT) SHORT1FROMMP(mp1);    /* MLE-window ID */
  19704.  usNotifyCode = MLN_KILLFOCUS;
  19705.  
  19706.  
  19707.  The MLN_KILLFOCUS notification message is sent whenever the window in a
  19708.  multiple-line entry field (MLE) window loses the input focus.
  19709.  
  19710.  
  19711.  Parameters
  19712.  
  19713.  id  Low word of mp1. Identifies the MLE window.
  19714.  
  19715.  usNotifyCode  High word of mp1. Set to MLN_KILLFOCUS.
  19716.  
  19717.  
  19718.  Return Value
  19719.  
  19720.  An application should return zero if it processes this message.
  19721.  
  19722.  
  19723.  See Also
  19724.  
  19725.  MLN_SETFOCUS, WM_CONTROL
  19726.  
  19727.  
  19728.  █    MLN_MARGIN
  19729.  ────────────────────────────────────────────────────────────────────────────
  19730.  
  19731.  
  19732.  WM_CONTROL
  19733.  id = (USHORT) SHORT1FROMMP(mp1);         /* MLE-window ID            */
  19734.  usNotifyCode = MLN_MARGIN;
  19735.  pmrg = (PMARGSTRUCT) PVOIDFROMMP(mp2);   /* pointer to MLEMARGSTRUCT */
  19736.  
  19737.  
  19738.  The MLN_MARGIN notification message is sent when the mouse moves over one of
  19739.  the margins of a multiple-line entry field (MLE).
  19740.  
  19741.  
  19742.  Parameters
  19743.  
  19744.  id  Low word of mp1. Identifies the MLE window.
  19745.  
  19746.  usNotifyCode  High word of mp1. Set to MLN_MARGIN.
  19747.  
  19748.  pmrg  Low and high words of mp2. Points to the MLEMARGSTRUCT structure that
  19749.  contains the margin data. The MLEMARGSTRUCT structure has the following
  19750.  form:
  19751.  
  19752.  typedef struct _MLEMARGSTRUCT {
  19753.     USHORT afMargins;
  19754.     USHORT usMouMsg;
  19755.     IPT    iptNear;
  19756.  } MLEMARGSTRUCT;
  19757.  
  19758.  
  19759.  
  19760.  
  19761.  For a full description, see Chapter 4, "Types, Macros, Structures."
  19762.  
  19763.  
  19764.  Return Value
  19765.  
  19766.  An application should return zero if you want the MLE to process this
  19767.  message.
  19768.  
  19769.  
  19770.  See Also
  19771.  
  19772.  WM_CONTROL
  19773.  
  19774.  
  19775.  
  19776.  
  19777.  █    MLN_MEMERROR
  19778.  ────────────────────────────────────────────────────────────────────────────
  19779.  
  19780.  
  19781.  WM_CONTROL
  19782.  id = (USHORT) SHORT1FROMMP(mp1);    /* MLE-window ID */
  19783.  usNotifyCode = MLN_MEMERROR;
  19784.  
  19785.  
  19786.  The MLN_MEMERROR notification message is sent if there is insufficient
  19787.  memory for the requested operation within a multiple-line entry field (MLE).
  19788.  
  19789.  
  19790.  
  19791.  Parameters
  19792.  
  19793.  id  Low word of mp1. Identifies the MLE window.
  19794.  
  19795.  usNotifyCode  High word of mp1. Set to MLN_MEMERROR.
  19796.  
  19797.  
  19798.  Return Value
  19799.  
  19800.  An application should return zero if it processes this message.
  19801.  
  19802.  
  19803.  See Also
  19804.  
  19805.  WM_CONTROL
  19806.  
  19807.  
  19808.  █    MLN_OVERFLOW
  19809.  ────────────────────────────────────────────────────────────────────────────
  19810.  
  19811.  
  19812.  WM_CONTROL
  19813.  id = (USHORT) SHORT1FROMMP(mp1);            /* MLE-window ID        */
  19814.  usNotifyCode = MLN_OVERFLOW;
  19815.  pmleover = (PMLEOVERFLOW) PVOIDFROMMP(mp2); /* point to MLEOVERFLOW */
  19816.  
  19817.  
  19818.  The MLN_OVERFLOW notification message is sent when an operation in a
  19819.  multiple-line entry field (MLE) would overflow a text limit or a format
  19820.  rectangle.
  19821.  
  19822.  
  19823.  Parameters
  19824.  
  19825.  id  Low word of mp1. Identifies the MLE window.
  19826.  
  19827.  usNotifyCode  High word of mp1. Set to MLN_OVERFLOW.
  19828.  
  19829.  pmleover  Low and high words of mp2. Points to an MLEOVERFLOW structure. The
  19830.  MLEOVERFLOW structure has the following form:
  19831.  
  19832.  typedef struct _MLEOVERFLOW {
  19833.     ULONG afErrInd;
  19834.     LONG nBytesOver;
  19835.     LONG pixHorzOver;
  19836.     LONG pixVertOver;
  19837.  }  MLEOVERFLOW;
  19838.  
  19839.  
  19840.  
  19841.  
  19842.  For a full description, see Chapter 4, "Types, Macros, Structures."
  19843.  
  19844.  
  19845.  Return Value
  19846.  
  19847.  The application should return TRUE to retry the operation.
  19848.  
  19849.  
  19850.  Comments
  19851.  
  19852.  Before returning TRUE, the application should perform some operation (for
  19853.  example, changing the dimensions of the format rectangle) that will enable
  19854.  the text to fit.
  19855.  
  19856.  Overflow caused by user-inserted text results in a MLN_PIXHORZOVERFLOW or
  19857.  MLN_VERTOVERFLOW notification message. Overflow caused by an application
  19858.  sending a message to the MLE results in a MLN_OVERFLOW message.
  19859.  
  19860.  
  19861.  See Also
  19862.  
  19863.  MLN_PIXHORZOVERFLOW, MLN_PIXVERTOVERFLOW, WM_CONTROL
  19864.  
  19865.  
  19866.  
  19867.  
  19868.  █    MLN_PIXHORZOVERFLOW
  19869.  ────────────────────────────────────────────────────────────────────────────
  19870.  
  19871.  
  19872.  WM_CONTROL
  19873.  id = (USHORT) SHORT1FROMMP(mp1);       /* MLE-window ID      */
  19874.  usNotifyCode = MLN_PIXHORZOVERFLOW;
  19875.  lOverFlow = LONGFROMMP(mp2);           /* amount of overflow */
  19876.  
  19877.  
  19878.  The MLN_PIXHORZOVERFLOW notification message is sent whenever user uses the
  19879.  keyboard to insert more text than can fit in the current format rectangle or
  19880.  the text limit of a multiple-line entry field (MLE).
  19881.  
  19882.  
  19883.  Parameters
  19884.  
  19885.  id  Low word of mp1. Identifies the MLE window.
  19886.  
  19887.  usNotifyCode  High word of mp1. Set to MLN_PIXHORZOVERFLOW.
  19888.  
  19889.  lOverFlow  Low and high words of mp2. The number of pels by which the
  19890.  operation overflows the current format rectangle.
  19891.  
  19892.  
  19893.  Return Value
  19894.  
  19895.  An application should return TRUE to retry the operation. If the application
  19896.  returns FALSE, the user cannot insert additional text.
  19897.  
  19898.  
  19899.  Comments
  19900.  
  19901.  Before returning TRUE, the application should perform some operation (for
  19902.  example, changing the dimensions of the format rectangle) that will enable
  19903.  the text to fit.
  19904.  
  19905.  
  19906.  See Also
  19907.  
  19908.  MLN_OVERFLOW, MLN_PIXVERTOVERFLOW, WM_CONTROL
  19909.  
  19910.  
  19911.  █    MLN_PIXVERTOVERFLOW
  19912.  ────────────────────────────────────────────────────────────────────────────
  19913.  
  19914.  
  19915.  WM_CONTROL
  19916.  id = (USHORT) SHORT1FROMMP(mp1);       /* MLE-window ID      */
  19917.  usNotifyCode = MLN_PIXVERTOVERFLOW;
  19918.  lOverFlow = LONGFROMMP(mp2);           /* amount of overflow */
  19919.  
  19920.  
  19921.  The MLN_PIXVERTOVERFLOW notification message is sent whenever a user uses
  19922.  the keyboard to insert more text than can fit in the current format
  19923.  rectangle or text limit of a multiple-line entry field (MLE).
  19924.  
  19925.  
  19926.  Parameters
  19927.  
  19928.  id  Low word of mp1. Identifies the MLE window.
  19929.  
  19930.  usNotifyCode  High word of mp1. Set to MLN_PIXVERTOVERFLOW.
  19931.  
  19932.  lOverFlow  Low and high words of mp2. The number of pels by which the
  19933.  operation overflowed the current format rectangle.
  19934.  
  19935.  
  19936.  Return Value
  19937.  
  19938.  An application should return TRUE to retry the operation. If the application
  19939.  returns FALSE, the user cannot insert additional text.
  19940.  
  19941.  
  19942.  Comments
  19943.  
  19944.  Before returning TRUE, the application should perform some operation (for
  19945.  example, changing the dimensions of the format rectangle) that will enable
  19946.  the text to fit.
  19947.  
  19948.  
  19949.  Example
  19950.  
  19951.  This example processes the MLN_PIXVERTOVERFLOW message by increasing the
  19952.  size of the format rectangle:
  19953.  
  19954.  MLEFORMATRECT mlefr;
  19955.  
  19956.  case MLN_PIXVERTOVERFLOW:
  19957.      mlefr.cyFormat += 100;
  19958.      WinSendMsg(hwndMle, MLM_SETFORMATRECT, (MPARAM) &mlefr,
  19959.          (MPARAM) MLFFMTRECT_LIMITVERT);
  19960.      return TRUE;
  19961.  
  19962.  
  19963.  
  19964.  
  19965.  
  19966.  See Also
  19967.  
  19968.  MLN_PIXHORZOVERFLOW, WM_CONTROL
  19969.  
  19970.  
  19971.  █    MLN_SEARCHPAUSE
  19972.  ────────────────────────────────────────────────────────────────────────────
  19973.  
  19974.  
  19975.  WM_CONTROL
  19976.  id = (USHORT) SHORT1FROMMP(mp1);         /* MLE-window ID      */
  19977.  usNotifyCode = MLN_SEARCHPAUSE;
  19978.  lCurOffset = (ULONG) LONGFROMMP(mp2);    /* position of search */
  19979.  
  19980.  
  19981.  The MLN_SEARCHPAUSE notification message is sent periodically while a
  19982.  multiple-line entry field (MLE) searches as a result of an MLM_SEARCH
  19983.  message. An application can use this message to terminate the search.
  19984.  
  19985.  
  19986.  Parameters
  19987.  
  19988.  id  Low word of mp1. Identifies the MLE window.
  19989.  
  19990.  usNotifyCode  High word of mp1. Set to MLN_SEARCHPAUSE.
  19991.  
  19992.  lCurOffset  Low and high words of mp2. Specifies the offset (number of
  19993.  characters from the beginning of the text) of the current character being
  19994.  searched for.
  19995.  
  19996.  
  19997.  Return Value
  19998.  
  19999.  The application should return FALSE to continue the search or TRUE to
  20000.  terminate the search.
  20001.  
  20002.  
  20003.  See Also
  20004.  
  20005.  MLM_SEARCH, WM_CONTROL
  20006.  
  20007.  
  20008.  █    MLN_SETFOCUS
  20009.  ────────────────────────────────────────────────────────────────────────────
  20010.  
  20011.  
  20012.  WM_CONTROL
  20013.  id = (USHORT) SHORT1FROMMP(mp1);    /* MLE-window ID */
  20014.  usNotifyCode = MLN_SETFOCUS;
  20015.  
  20016.  
  20017.  The MLN_SETFOCUS notification message is sent when the window in a
  20018.  multiple-line entry field (MLE) receives the input focus.
  20019.  
  20020.  
  20021.  Parameters
  20022.  
  20023.  id  Low word of mp1. Identifies the MLE window.
  20024.  
  20025.  usNotifyCode  High word of mp1. Set to MLN_SETFOCUS.
  20026.  
  20027.  
  20028.  Return Value
  20029.  
  20030.  An application should return zero if it processes this message.
  20031.  
  20032.  
  20033.  See Also
  20034.  
  20035.  MLN_KILLFOCUS, WM_CONTROL
  20036.  
  20037.  
  20038.  █    MLN_TEXTOVERFLOW
  20039.  ────────────────────────────────────────────────────────────────────────────
  20040.  
  20041.  
  20042.  WM_CONTROL
  20043.  id = (USHORT) SHORT1FROMMP(mp1);      /* MLE-window ID         */
  20044.  usNotifyCode = MLN_TEXTOVERFLOW;
  20045.  cchOver = (ULONG) LONGFROMMP(mp2);    /* characters over limit */
  20046.  
  20047.  
  20048.  The MLN_TEXTOVERFLOW notification message is sent when an operation in a
  20049.  multiple-line entry field (MLE) exceeds the current text limit.
  20050.  
  20051.  
  20052.  Parameters
  20053.  
  20054.  id  Low word of mp1. Identifies the MLE window.
  20055.  
  20056.  usNotifyCode  High word of mp1. Set to MLN_TEXTOVERFLOW.
  20057.  
  20058.  cchOver  Low and high words of mp2. Specifies the number of characters by
  20059.  which the text limit would overflow if the present operation completes.
  20060.  
  20061.  
  20062.  Return Value
  20063.  
  20064.  An application should return TRUE to retry the operation. If the application
  20065.  returns FALSE, the user cannot insert additional text.
  20066.  
  20067.  
  20068.  Comments
  20069.  
  20070.  Before returning TRUE, the application should perform some operation (for
  20071.  example, changing the dimensions of the format rectangle) that will enable
  20072.  the text to fit.
  20073.  
  20074.  
  20075.  See Also
  20076.  
  20077.  MLN_OVERFLOW, WM_CONTROL
  20078.  
  20079.  
  20080.  █    MLN_UNDOOVERFLOW
  20081.  ────────────────────────────────────────────────────────────────────────────
  20082.  
  20083.  
  20084.  WM_CONTROL
  20085.  id = (USHORT) SHORT1FROMMP(mp1);    /* MLE-window ID */
  20086.  usNotifyCode = MLN_UNDOOVERFLOW;
  20087.  
  20088.  
  20089.  The MLN_UNDOOVERFLOW notification message is sent by a multiple-line entry
  20090.  field (MLE) if a text change cannot be undone because the amount of text
  20091.  involved exceeds the undo limit. This includes text entry, deletion, and
  20092.  cutting and pasting.
  20093.  
  20094.  
  20095.  Parameters
  20096.  
  20097.  id  Low word of mp1. Identifies the MLE window.
  20098.  
  20099.  usNotifyCode  High word of mp1. Set to MLN_UNDOOVERFLOW.
  20100.  
  20101.  
  20102.  Return Value
  20103.  
  20104.  An application should return zero if it processes this message.
  20105.  
  20106.  
  20107.  See Also
  20108.  
  20109.  MLM_CUT, MLM_DELETE, MLM_INSERT, MLM_PASTE, WM_CONTROL
  20110.  
  20111.  
  20112.  █    MLN_VSCROLL
  20113.  ────────────────────────────────────────────────────────────────────────────
  20114.  
  20115.  
  20116.  WM_CONTROL
  20117.  id = (USHORT) SHORT1FROMMP(mp1);      /* control-window ID */
  20118.  usNotifyCode = MLN_VSCROLL;
  20119.  sPos = (USHORT) SHORT1FROMMP(mp2);    /* slider position   */
  20120.  
  20121.  
  20122.  The MLN_VSCROLL notification message is sent to the owner of a multiple-line
  20123.  entry field (MLE) window when a vertical scroll event occurs.
  20124.  
  20125.  
  20126.  Parameters
  20127.  
  20128.  id  Low word of mp1. Identifies the MLE window.
  20129.  
  20130.  usNotifyCode  High word of mp1. Set to MLN_VSCROLL.
  20131.  
  20132.  sPos  Low word of mp2. Specifies the top line of the display text.
  20133.  
  20134.  
  20135.  Return Value
  20136.  
  20137.  An application should return zero if it processes this message.
  20138.  
  20139.  
  20140.  See Also
  20141.  
  20142.  MLN_HSCROLL, WM_CONTROL
  20143.  
  20144.  
  20145.  █    MM_DISMISSMENU
  20146.  ────────────────────────────────────────────────────────────────────────────
  20147.  
  20148.  
  20149.  MM_DISMISSMENU
  20150.  mp1 = 0L;    /* not used, must be zero */
  20151.  mp2 = 0L;    /* not used, must be zero */
  20152.  
  20153.  
  20154.  An application sends an MM_DISMISSMENU message to dismiss a pull-down menu.
  20155.  Ordinarily, an application sends this message only to a pull-down menu that
  20156.  has the MIA_NODISMISS attribute.
  20157.  
  20158.  
  20159.  Parameters
  20160.  
  20161.  This message does not use any parameters.
  20162.  
  20163.  
  20164.  Return Value
  20165.  
  20166.  This message does not return a value.
  20167.  
  20168.  
  20169.  See Also
  20170.  
  20171.  MM_ENDMENUMODE
  20172.  
  20173.  
  20174.  █    MM_QUERYSELITEMID
  20175.  ────────────────────────────────────────────────────────────────────────────
  20176.  
  20177.  
  20178.  MM_QUERYSELITEMID
  20179.  mp1 = MPFROM2SHORT(0, (BOOL) fIncludeSubMenus);
  20180.  mp2 = 0L;    /* must be zero */
  20181.  
  20182.  
  20183.  An application sends an MM_QUERYSELITEMID message to determine the
  20184.  identifier of the selected menu item.
  20185.  
  20186.  
  20187.  Parameters
  20188.  
  20189.  fIncludeSubMenus  High word of mp1. Specifies whether to include submenus in
  20190.  the search. A value of TRUE includes submenus.
  20191.  
  20192.  
  20193.  Return Value
  20194.  
  20195.  The return value is the identifier of the selected item, MIT_NONE if no item
  20196.  is selected, or MID_ERROR if an error occurs.
  20197.  
  20198.  
  20199.  See Also
  20200.  
  20201.  MM_SELECTITEM
  20202.  
  20203.  
  20204.  Changes
  20205.  
  20206.  The fIncludeSubMenus parameter has been added.
  20207.  
  20208.  
  20209.  █    MOU_DISPLAYMODECHANGE
  20210.  ────────────────────────────────────────────────────────────────────────────
  20211.  
  20212.  USHORT DosDevIOCtl  (0L, 0L, 0x005D, 0x0007, hDevice)
  20213.  
  20214.  HFILE  hDevice;                   /*device handle */
  20215.  
  20216.  
  20217.  The MOU_DISPLAYMODECHANGE function notifies the mouse device driver that a
  20218.  display-mode change is complete.
  20219.  
  20220.  
  20221.  Parameters
  20222.  
  20223.  hDevice  Identifies the pointing device that receives the device-control
  20224.  function. This handle must have been created previously by using the DosOpen
  20225.  function.
  20226.  
  20227.  
  20228.  Return Value
  20229.  
  20230.  The return value is zero if the function is successful. Otherwise, it is an
  20231.  error value.
  20232.  
  20233.  
  20234.  Comments
  20235.  
  20236.  The MOU_DISPLAYMODECHANGE function notifies the mouse that a mode switch is
  20237.  complete and that drawing is allowed. The pointer is redrawn if it was
  20238.  hidden when the mode switch began.
  20239.  
  20240.  
  20241.  See Also
  20242.  
  20243.  DosDevIOCtl, DosOpen, VioSetMode
  20244.  
  20245.  
  20246.  █    MOU_SETPROTDRAWADDRESS
  20247.  ────────────────────────────────────────────────────────────────────────────
  20248.  
  20249.  USHORT DosDevIOCtl  (pbDrawData, pbFunction, 0x005A, 0x0007, hDevice)
  20250.  
  20251.  PBYTE  pbDrawData;                /*pointer to drawing data */
  20252.  
  20253.  PBYTE  pbFunction;                /*pointer to structure with drawing
  20254.                                    function */
  20255.  
  20256.  HFILE  hDevice;                   /*device handle */
  20257.  
  20258.  
  20259.  The MOU_SETPROTDRAWADDRESS function notifies the mouse device driver of the
  20260.  address of a protected-mode pointer-draw function. This function is valid
  20261.  for protected mode only.
  20262.  
  20263.  
  20264.  Parameters
  20265.  
  20266.  pbDrawData  Points to the PTRDRAWDATA structure. This structure has the
  20267.  following form:
  20268.  
  20269.  typedef struct _PTRDRAWDATA {
  20270.      USHORT cb;                  /* length                   */
  20271.      USHORT usConfig;            /* which display to draw on */
  20272.      USHORT usFlag               /* Application/BVS Flag     */
  20273.  } PTRDRAWDATA;
  20274.  
  20275.  
  20276.  
  20277.  
  20278.  For a full description, see Chapter 4, "Types, Macros, Structures."
  20279.  
  20280.  pbFunction  Points to the PTRDRAWFUNCTION structure that contains the
  20281.  address of the pointer-draw function. This structure has the following form:
  20282.  
  20283.  
  20284.  typedef struct _PTRDRAWFUNCTION {
  20285.      PFN pfnDraw;
  20286.      PCH pchDataSeg;
  20287.  } PTRDRAWFUNCTION;
  20288.  
  20289.  
  20290.  
  20291.  
  20292.  hDevice  Identifies the pointing device that receives the device-control
  20293.  function. The handle must have been created previously by using the DosOpen
  20294.  function.
  20295.  
  20296.  
  20297.  Return Value
  20298.  
  20299.  The return value is zero if the function is successful or an error value if
  20300.  an error occurs.
  20301.  
  20302.  
  20303.  Comments
  20304.  
  20305.  The pointer-draw routine is an installed, pseudo-character device driver.
  20306.  The mouse handler must do the following:
  20307.  
  20308.    ■   Open the pointer-draw device driver.
  20309.  
  20310.    ■   Query the pointer-draw device driver for the address of its entry
  20311.        point.
  20312.  
  20313.    ■   Pass the resulting address of the pointer-draw entry point to the
  20314.        mouse device driver that uses this function.
  20315.  
  20316.  
  20317.  
  20318.  
  20319.  See Also
  20320.  
  20321.  DosOpen, MOU_SETREALDRAWADDRESS
  20322.  
  20323.  
  20324.  Changes
  20325.  
  20326.  The first parameter of the DosDevIOCtl function is now pbDrawData, which
  20327.  points to a PTRDRAWDATA structure.
  20328.  
  20329.  
  20330.  █    MOU_SETREALDRAWADDRESS
  20331.  ────────────────────────────────────────────────────────────────────────────
  20332.  
  20333.  USHORT DosDevIOCtl  (pvConfig, pbFunction, 0x005B, 0x0007, hDevice)
  20334.  
  20335.  PVOID  pvConfig;                  /*pointer to configuration structure */
  20336.  
  20337.  PBYTE  pbFunction;                /*pointer to structure with function */
  20338.  
  20339.  HFILE  hDevice;                   /*device handle */
  20340.  
  20341.  
  20342.  The MOU_SETREALDRAWADDRESS function notifies the real-mode mouse device
  20343.  driver of the entry point of a real-mode pointer-draw routine. This function
  20344.  is intended for use by Session Manager at the end of system initialization
  20345.  and is valid for real mode only.
  20346.  
  20347.  
  20348.  Parameters
  20349.  
  20350.  pvConfig  Points to the VIOCONFIGINFO structure that contains information
  20351.  about configuration of the default display. The VIOCONFIGINFO structure has
  20352.  the following format:
  20353.  
  20354.  typedef struct _VIOCONFIGINFO {
  20355.      USHORT  cb     ;
  20356.      USHORT  adapter;
  20357.      USHORT  display;
  20358.      ULONG   cbMemory;
  20359.      USHORT  Configuration;
  20360.      USHORT  VDHVersion;
  20361.      USHORT  Flags;
  20362.      ULONG   HWBufferSize;
  20363.      ULONG   FullSaveSize;
  20364.      ULONG   PartSaveSize;
  20365.      USHORT  EMAdaptersOFF;
  20366.      USHORT  EMDisplaysOFF;
  20367.  } VIOCONFIGINFO;
  20368.  
  20369.  
  20370.  
  20371.  
  20372.  For a full description, see Chapter 4, "Types, Macros, Structures."
  20373.  
  20374.  pbFunction  Points to the PTRDRAWFUNCTION structure that contains the
  20375.  address of the pointer-draw function. The PTRDRAWFUNCTION structure has the
  20376.  following form:
  20377.  
  20378.  typedef struct _PTRDRAWFUNCTION {
  20379.      PFN    pfnDraw;
  20380.      PCH    pchDataSeg;
  20381.  } PTRDRAWFUNCTION;
  20382.  
  20383.  
  20384.  
  20385.  
  20386.  For a full description, see Chapter 4, "Types, Macros, Structures."
  20387.  
  20388.  hDevice  Identifies the pointing device that receives the device-control
  20389.  function. The handle must have been created previously by using the DosOpen
  20390.  function.
  20391.  
  20392.  
  20393.  Return Value
  20394.  
  20395.  The return value is zero if the function is successful or an error value if
  20396.  an error occurs.
  20397.  
  20398.  
  20399.  See Also
  20400.  
  20401.  DosOpen, MOU_SETPROTDRAWADDRESS
  20402.  
  20403.  
  20404.  Changes
  20405.  
  20406.  The first parameter now points to a VIOCONFIGINFO structure.
  20407.  
  20408.  
  20409.  █    MOU_UPDATEDISPLAYMODE
  20410.  ────────────────────────────────────────────────────────────────────────────
  20411.  
  20412.  USHORT DosDevIOCtl  (pvConfigInfo, pviomi, 0x0051, 0x0007, hDevice)
  20413.  
  20414.  PVOID  pvConfigInfo;              /*pointer to structure with
  20415.                                    configuration info */
  20416.  
  20417.  PVIOMODEINFO  pviomi;             /*pointer to structure with screen mode
  20418.                                    */
  20419.  
  20420.  HFILE  hDevice;                   /*device handle */
  20421.  
  20422.  
  20423.  The MOU_UPDATEDISPLAYMODE function notifies the mouse device driver that the
  20424.  display mode has been modified.
  20425.  
  20426.  
  20427.  Parameters
  20428.  
  20429.  pvConfigInfo  Points to the VIOCONFIGINFO structure that contains the
  20430.  current display-configuration information. The VIOCONFIGINFO structure has
  20431.  the following form:
  20432.  
  20433.  typedef struct _VIOCONFIGINFO {
  20434.      USHORT  cb;
  20435.      USHORT  adapter;
  20436.      USHORT  display;
  20437.      ULONG   cbMemory;
  20438.      USHORT  Configuration;
  20439.      USHORT  VDHVersion;
  20440.      USHORT  Flags;
  20441.      ULONG   HWBufferSize;
  20442.      ULONG   FullSaveSize;
  20443.      ULONG   PartSaveSize;
  20444.      USHORT  EMAdaptersOFF;
  20445.      USHORT  EMDisplaysOFF;
  20446.   } VIOCONFIGINFO;
  20447.  
  20448.  
  20449.  
  20450.  
  20451.  For a full description, see Chapter 4, "Types, Macros, Structures."
  20452.  
  20453.  pviomi  Points to the VIOMODEINFO structure that contains the display-mode
  20454.  information. The VIOMODEINFO structure has the following form:
  20455.  
  20456.  typedef struct _VIOMODEINFO {
  20457.      USHORT cb;
  20458.      UCHAR  fbType;
  20459.      UCHAR  color;
  20460.      USHORT col;
  20461.      USHORT row;
  20462.      USHORT hres;
  20463.      USHORT vres;
  20464.      UCHAR  fmt_ID;
  20465.      UCHAR  attrib;
  20466.      ULONG  buf_addr;
  20467.      ULONG  buf_length;
  20468.      ULONG  full_length;
  20469.      ULONG  partial_length;
  20470.      PCH    ext_data_addr;
  20471.  } VIOMODEINFO;
  20472.  
  20473.  
  20474.  
  20475.  
  20476.  For a full description, see Chapter 4, "Types, Macros, Structures."
  20477.  
  20478.  hDevice  Identifies the pointing device that receives the device-control
  20479.  function. This handle must have been created previously by using the DosOpen
  20480.  function.
  20481.  
  20482.  
  20483.  Return Value
  20484.  
  20485.  The return value is zero if the function is successful or an error value if
  20486.  an error occurs.
  20487.  
  20488.  
  20489.  Comments
  20490.  
  20491.  When the video I/O subsystem or registered video I/O subsystem sets the
  20492.  display mode, it must notify the mouse device driver prior to switching
  20493.  display modes, in order to synchronize the mouse device driver's functions
  20494.  that update the pointer.
  20495.  
  20496.  
  20497.  See Also
  20498.  
  20499.  DosOpen, VioSetMode
  20500.  
  20501.  
  20502.  Changes
  20503.  
  20504.  This function has been updated to reflect changes to the VIOMODEINFO and
  20505.  VIOCONFIGINFO structures.
  20506.  
  20507.  
  20508.  █    MOU_VER
  20509.  ────────────────────────────────────────────────────────────────────────────
  20510.  
  20511.  USHORT DosDevIOCtl  (pusVersion, 0L, 0x006A, 0x0007, hDevice)
  20512.  
  20513.  PUSHORT  pusVersion;              /*pointer to version number */
  20514.  
  20515.  HFILE  hDevice;                   /*device handle */
  20516.  
  20517.  
  20518.  The MOU_VER function returns the version number of the mouse driver.
  20519.  
  20520.  
  20521.  Parameters
  20522.  
  20523.  pusVersion  Points to a data area in which the version number of the mouse
  20524.  driver is returned.
  20525.  
  20526.  hDevice  Identifies the pointing device that receives the device-control
  20527.  function. This handle must have been created previously by using the DosOpen
  20528.  function.
  20529.  
  20530.  
  20531.  Return Value
  20532.  
  20533.  The return value is zero if the function is successful. Otherwise, it is an
  20534.  error value.
  20535.  
  20536.  
  20537.  Comments
  20538.  
  20539.  The MOU_VER function returns 0x0001 as the version number of the mouse
  20540.  driver to indicate that the following features are supported. These features
  20541.  are new for MS OS/2 versions 1.2 and later.
  20542.  
  20543.  Function                          Change
  20544.  ────────────────────────────────────────────────────────────────────────────
  20545.  
  20546.  MOU_DISPLAYMODECHANGE             New IOCtl function.
  20547.  
  20548.  MOU_SETPROTDRAWADDRESS            New pbDrawData parameter.
  20549.  
  20550.  MOU_SETREALDRAWADDRESS            New pvConfig parameter.
  20551.  
  20552.  MOU_UPDATEDISPLAYMODE             New pvConfigInfo parameter.
  20553.  
  20554.  MOU_UPDATEDISPLAYMODE             Size of VIOMODEINFO structure increased
  20555.                                    from 12 to 34 bytes.
  20556.  
  20557.  MOU_VER                           New IOCtl function.
  20558.  
  20559.  
  20560.  
  20561.  The MOU_VER function should be used to determine the version number of the
  20562.  mouse device driver before any of these features are used, in order to
  20563.  maintain compatibility with earlier versions of MS OS/2.
  20564.  
  20565.  
  20566.  See Also
  20567.  
  20568.  DosDevIOCtl, DosOpen
  20569.  
  20570.  
  20571.  █    MouGetNumQueEl
  20572.  ────────────────────────────────────────────────────────────────────────────
  20573.  
  20574.  USHORT MouGetNumQueEl  (pmouqi, hmou)
  20575.  
  20576.  PMOUQUEINFO  pmouqi;              /*pointer to structure for number of
  20577.                                    events */,
  20578.  
  20579.  HMOU  hmou;                       /*mouse handle */
  20580.  
  20581.  
  20582.  The MouGetNumQueEl function retrieves the number of events in the
  20583.  mouse-event queue.
  20584.  
  20585.  
  20586.  Parameters
  20587.  
  20588.  pmouqi  Points to the MOUQUEINFO structure that receives the number of
  20589.  events in the mouse-event queue. The MOUQUEINFO structure has the following
  20590.  form:
  20591.  
  20592.  typedef struct _MOUQUEINFO {
  20593.      USHORT cEvents;
  20594.      USHORT cmaxEvents;
  20595.  } MOUQUEINFO;
  20596.  
  20597.  
  20598.  
  20599.  
  20600.  For a full description, see Chapter 4, "Types, Macros, Structures."
  20601.  
  20602.  hmou  Identifies the mouse. This handle must have been created previously by
  20603.  using the MouOpen function.
  20604.  
  20605.  
  20606.  Return Value
  20607.  
  20608.  The return value is zero if the function is successful. Otherwise, it is an
  20609.  error value, which may be the following:
  20610.  
  20611.       ERROR_MOUSE_NO_DEVICE
  20612.  
  20613.  
  20614.  
  20615.  
  20616.  
  20617.  Example
  20618.  
  20619.  This example creates a mouse handle, enables the mouse pointer to be drawn,
  20620.  and runs within an infinite for loop until there are no events in the queue.
  20621.  
  20622.  
  20623.  HMOU hmou;
  20624.  MOUEVENTINFO mouevEvent;
  20625.  MOUQUEINFO mouqi;
  20626.  USHORT fWait = FALSE;
  20627.  MouOpen(0L, &hmou);
  20628.  MouDrawPtr(hmou);
  20629.  for (;;) {
  20630.      MouGetNumQueEl(&mouqi, hmou);      /* retrieves queue         */
  20631.      if (mouqi.cEvents > 1)             /* until the last queue... */
  20632.          MouReadEventQue(&mouevEvent, &fWait, hmou);
  20633.      else
  20634.          break;
  20635.  }
  20636.  
  20637.  
  20638.  
  20639.  
  20640.  
  20641.  See Also
  20642.  
  20643.  MouFlushQue, MouOpen, MouReadEventQue
  20644.  
  20645.  
  20646.  Corrections
  20647.  
  20648.  The example was lacking a closing parenthesis at the end of the
  20649.  MouGetNumQueEl function call. This has been added.
  20650.  
  20651.  
  20652.  █    MouSynch
  20653.  ────────────────────────────────────────────────────────────────────────────
  20654.  
  20655.  USHORT MouSynch  (fWait)
  20656.  
  20657.  USHORT  fWait;                    /*wait/no-wait flag */
  20658.  
  20659.  
  20660.  The MouSynch function synchronizes access to the mouse. This function should
  20661.  be used by a Mou subsystem to prevent more than one process from accessing
  20662.  the mouse handle at any one time.
  20663.  
  20664.  
  20665.  Parameters
  20666.  
  20667.  fWait  Specifies whether to wait if the mouse device driver is currently
  20668.  busy. If this parameter is FALSE, the function returns control immediately
  20669.  without waiting for the device to become free. If this parameter is TRUE,
  20670.  the function waits until the mouse handle is free.
  20671.  
  20672.  
  20673.  Return Value
  20674.  
  20675.  The return value is zero if the function is successful. Otherwise, it is an
  20676.  error value.
  20677.  
  20678.  
  20679.  Comments
  20680.  
  20681.  The MouSynch function requests an exclusive system semaphore that clears
  20682.  when the Mou subsystem returns to the mouse router. The MouSynch function
  20683.  blocks all other threads within a screen group until the semaphore clears.
  20684.  
  20685.  A registered mouse subsystem should not issue the MouSynch function when the
  20686.  base video subsystem (BVS) issues MouOpen and MouClose functions. A
  20687.  registered mouse subsystem must provide the required level of serialization
  20688.  for the MouOpen and MouClose functions without calling MouSynch. This
  20689.  special processing is required because MouOpen and MouClose are issued by
  20690.  BVS on the VioSetMode path. The VioSetMode function can be issued, in turn,
  20691.  by a VioSavRedrawWait thread. You can assume the synchronization semaphore
  20692.  was already held by another thread blocked by a call to the MouReadEventQue
  20693.  function.
  20694.  
  20695.  Note that if a save/redraw wait thread issues the VioSetMode function, and
  20696.  if BVS in turn issues the MouOpen or MouClose function and the mouse
  20697.  subsystem in turn issues the MouSynch function, the screen switch will be
  20698.  blocked and the system will "hang."
  20699.  
  20700.  
  20701.  See Also
  20702.  
  20703.  DosCloseSem, DosDevIOCtl, MouClose MouOpen, MouReadEventQue, MouRegister,
  20704.  VioSavRedrawWait, VioSetMode
  20705.  
  20706.  
  20707.  Corrections
  20708.  
  20709.  A registered mouse subsystem should not issue MouSynch when the base video
  20710.  subsystem (BVS) issues MouOpen and MouClose functions. A registered mouse
  20711.  subsystem must provide the required level of serialization for MouOpen and
  20712.  MouClose without calling MouSynch. This special processing is required
  20713.  because MouOpen and MouClose are issued by BVS on the VioSetMode path. The
  20714.  VioSetMode function can be issued, in turn, by a VioSavRedrawWait thread.
  20715.  You can assume the synchronization semaphore was already held by another
  20716.  thread blocked by a call to MouReadEventQue.
  20717.  
  20718.  Note that if a save/redraw wait thread issues the VioSetMode function, if
  20719.  BVS in turn issues the MouOpen or MouClose function, and the mouse subsystem
  20720.  in turn issues the MouSynch function, the screen switch will be blocked and
  20721.  the system will "hang."
  20722.  
  20723.  
  20724.  █    PicIchg
  20725.  ────────────────────────────────────────────────────────────────────────────
  20726.  
  20727.  BOOL PicIchg  (hab, pszSrcFile, pszDestFile, lType)
  20728.  
  20729.  HAB  hab;                         /*anchor-block handle */
  20730.  
  20731.  PSZ  pszSrcFile;                  /*pointer to source-file name */
  20732.  
  20733.  PSZ  pszDestFile;                 /*pointer to destination-file name */
  20734.  
  20735.  LONG  lType;                      /*translation type */
  20736.  
  20737.  
  20738.  The PicIchg function converts an interchange file to a metafile, or converts
  20739.  a symbol file to a font file.
  20740.  
  20741.  
  20742.  Parameters
  20743.  
  20744.  hab  Identifies the anchor block.
  20745.  
  20746.  pszSrcFile  Points to the string that contains the name of the source file.
  20747.  This name must be a valid MS OS/2 filename.
  20748.  
  20749.  pszDestFile  Points to the string that contains the name of the destination
  20750.  file. This name must be a valid MS OS/2 filename.
  20751.  
  20752.  lType  Specifies the type of conversion requested. This parameter can be one
  20753.  of the following values:
  20754.  
  20755.  Value                             Meaning
  20756.  ────────────────────────────────────────────────────────────────────────────
  20757.  
  20758.  PIC_PIFTOMET                      Converts an interchange file to a
  20759.                                    metafile.
  20760.  
  20761.  PIC_SSTOFONT                      Converts a symbol set to a font.
  20762.  
  20763.  
  20764.  
  20765.  Return Value
  20766.  
  20767.  The return value is TRUE if the conversion is successful or FALSE if an
  20768.  error occurs.
  20769.  
  20770.  
  20771.  Comments
  20772.  
  20773.  Any reference to an internal symbol or pattern set is changed to a reference
  20774.  to the default font character set. Any reference to a line-type set is
  20775.  changed to a reference to the default line type.
  20776.  
  20777.  Only outline fonts are supported.
  20778.  
  20779.  
  20780.  See Also
  20781.  
  20782.  PicPrint
  20783.  
  20784.  
  20785.  █    PicPrint
  20786.  ────────────────────────────────────────────────────────────────────────────
  20787.  
  20788.  BOOL PicPrint  (hab, pszSrcFile, lType, pszParms)
  20789.  
  20790.  HAB  hab;                         /*anchor-block handle */
  20791.  
  20792.  PSZ  pszSrcFile;                  /*pointer to source-file name */
  20793.  
  20794.  LONG  lType;                      /*type of file to print */
  20795.  
  20796.  PSZ  pszParms;                    /*spooler parameters */
  20797.  
  20798.  
  20799.  The PicPrint function prints a picture file.
  20800.  
  20801.  
  20802.  Parameters
  20803.  
  20804.  hab  Identifies the anchor block.
  20805.  
  20806.  pszSrcFile  Points to the string that contains the name of the source file.
  20807.  This name must be a valid MS OS/2 filename.
  20808.  
  20809.  lType  Specifies the type of file to print. This parameter can be one of the
  20810.  following values:
  20811.  
  20812.  Value                             Meaning
  20813.  ────────────────────────────────────────────────────────────────────────────
  20814.  
  20815.  PIP_MF                            Prints a metafile.
  20816.  
  20817.  PIP_PIF                           Prints an interchange file.
  20818.  
  20819.  
  20820.  
  20821.  pszParms  Points to the string that contains spooler parameters.
  20822.  
  20823.  
  20824.  Return Value
  20825.  
  20826.  The return value is TRUE if the print operation is successful or FALSE if an
  20827.  error occurs.
  20828.  
  20829.  
  20830.  See Also
  20831.  
  20832.  PicIchg
  20833.  
  20834.  
  20835.  █    PL_ALTERED
  20836.  ────────────────────────────────────────────────────────────────────────────
  20837.  
  20838.  
  20839.  PL_ALTERED
  20840.  hiniUser = HWNDFROMMP(mp1);    /* handle of user-profile file   */
  20841.  hiniSystem = HWNDFROMMP(mp2);  /* handle of system-profile file */
  20842.  
  20843.  
  20844.  A PL_ALTERED message is broadcast to all frame windows when an application
  20845.  calls the PrfReset function.
  20846.  
  20847.  
  20848.  Parameters
  20849.  
  20850.  hiniUser  Low and high words of mp1. Identifies the user-profile file.
  20851.  
  20852.  hiniSystem  Low and high words of mp2. Identifies the system-profile file.
  20853.  
  20854.  
  20855.  Return Value
  20856.  
  20857.  An application should return zero if it processes this message.
  20858.  
  20859.  
  20860.  See Also
  20861.  
  20862.  PrfReset
  20863.  
  20864.  
  20865.  █    PrfAddProgram
  20866.  ────────────────────────────────────────────────────────────────────────────
  20867.  
  20868.  HPROGRAM PrfAddProgram  (hini, pprogde, hGroup)
  20869.  
  20870.  HINI  hini;                       /*initialization-file handle */
  20871.  
  20872.  PPROGDETAILS  pprogde;            /*address of structure with program
  20873.                                    information */
  20874.  
  20875.  HPROGRAM  hGroup;                 /*program-group handle */
  20876.  
  20877.  
  20878.  The PrfAddProgram function adds a program to the program list of a group in
  20879.  Desktop Manager. The same program title can be used in different groups, but
  20880.  the program titles within a group must each be unique.
  20881.  
  20882.  
  20883.  Parameters
  20884.  
  20885.  hini  Identifies the file to which the program information is added. This
  20886.  parameter can be an initialization-file handle obtained by using the
  20887.  PrfOpenProfile function, or it can be the value HINI_USERPROFILE, specifying
  20888.  the user-profile file.
  20889.  
  20890.  pprogde  Points to the PROGDETAILS structure that contains program
  20891.  information for the program being added to Desktop Manager. The PROGDETAILS
  20892.  structure has the following form:
  20893.  
  20894.  typedef struct _PROGDETAILS {
  20895.      ULONG    Length;
  20896.      PROGTYPE progt;
  20897.      USHORT   pad1[3];
  20898.      PSZ      pszTitle;
  20899.      PSZ      pszExecutable;
  20900.      PSZ      pszParameters;
  20901.      PSZ      pszStartupDir;
  20902.      PSZ      pszIcon;
  20903.      PSZ      pszEnvironment;
  20904.      SWP      swpInitial;
  20905.      USHORT   pad2[5];
  20906.  } PROGDETAILS;
  20907.  
  20908.  
  20909.  
  20910.  
  20911.  For a full description, see Chapter 4, "Types, Macros, Structures."
  20912.  
  20913.  hGroup  Identifies the program group to which the program title is added. If
  20914.  this parameter is zero and the hini parameter is HINI_USERPROFILE, the
  20915.  program is added to the first group defined in Desktop Manager.
  20916.  
  20917.  
  20918.  Return Value
  20919.  
  20920.  The return value is the handle for the added program if the function is
  20921.  successful or NULL if an error occurs.
  20922.  
  20923.  
  20924.  Errors
  20925.  
  20926.  Use the WinGetLastError function to retrieve the error value, which may be
  20927.  one of the following:
  20928.  
  20929.       PMERR_DUPLICATE_TITLE
  20930.       PMERR_GROUP_PROTECTED
  20931.       PMERR_INSUFF_SPACE_TO_ADD
  20932.       PMERR_INVALID_GROUP_HANDLE
  20933.       PMERR_INVALID_PROGRAM_CATEGORY
  20934.       PMERR_INVALID_TARGET_HANDLE
  20935.       PMERR_INVALID_TITLE
  20936.       PMERR_MEMORY_ALLOCATION_ERR
  20937.       PMERR_MEMORY_DEALLOCATION_ERR
  20938.       PMERR_NOT_CURRENT_PL_VERSION
  20939.       PMERR_NOT_IN_IDX
  20940.  
  20941.  
  20942.  
  20943.  
  20944.  
  20945.  See Also
  20946.  
  20947.  PrfCreateGroup, PrfOpenProfile, PrfQueryDefinition, PrfQueryProgramTitles,
  20948.  WinAddProgram
  20949.  
  20950.  
  20951.  
  20952.  
  20953.  █    PrfChangeProgram
  20954.  ────────────────────────────────────────────────────────────────────────────
  20955.  
  20956.  BOOL PrfChangeProgram  (hini, hprog, pprogde)
  20957.  
  20958.  HINI  hini;                       /*initialization-file handle */
  20959.  
  20960.  HPROGRAM  hprog;                  /*program handle */
  20961.  
  20962.  PPROGDETAILS  pprogde;            /*address of structure with replacement
  20963.                                    info. */
  20964.  
  20965.  
  20966.  The PrfChangeProgram function changes the information stored in Desktop
  20967.  Manager about a program or group.
  20968.  
  20969.  
  20970.  Parameters
  20971.  
  20972.  hini  Identifies the file that contains the program or group information to
  20973.  change. This parameter can be an initialization-file handle obtained by
  20974.  using the PrfOpenProfile function, or it can be the value HINI_USERPROFILE,
  20975.  specifying the user-profile file.
  20976.  
  20977.  hprog  Identifies the program or group whose information is to change. If
  20978.  this parameter is a group handle, only the progt and pszTitle fields can be
  20979.  changed.
  20980.  
  20981.  pprogde  Points to the PROGDETAILS structure that contains the new program
  20982.  information. The PROGDETAILS structure has the following form:
  20983.  
  20984.  typedef struct _PROGDETAILS {
  20985.      ULONG    Length;
  20986.      PROGTYPE progt;
  20987.      USHORT   pad1[3];
  20988.      PSZ      pszTitle;
  20989.      PSZ      pszExecutable;
  20990.      PSZ      pszParameters;
  20991.      PSZ      pszStartupDir;
  20992.      PSZ      pszIcon;
  20993.      PSZ      pszEnvironment;
  20994.      SWP      swpInitial;
  20995.      USHORT   pad2[5];
  20996.  } PROGDETAILS;
  20997.  
  20998.  
  20999.  
  21000.  
  21001.  For a full description, see Chapter 4, "Types, Macros, Structures."
  21002.  
  21003.  
  21004.  Return Value
  21005.  
  21006.  The return value is TRUE if the function is successful or FALSE if an error
  21007.  occurs.
  21008.  
  21009.  
  21010.  Errors
  21011.  
  21012.  Use the WinGetLastError function to retrieve the error value, which may be
  21013.  one of the following:
  21014.  
  21015.       PMERR_DUPLICATE_TITLE
  21016.       PMERR_GROUP_PROTECTED
  21017.       PMERR_INVALID_PROGRAM_CATEGORY
  21018.       PMERR_INVALID_TARGET_HANDLE
  21019.       PMERR_INVALID_TITLE
  21020.       PMERR_MEMORY_ALLOCATION_ERR
  21021.       PMERR_MEMORY_DEALLOCATION_ERR
  21022.       PMERR_NOT_IN_IDX
  21023.       PMERR_UNKNOWN_APIPKT
  21024.  
  21025.  
  21026.  
  21027.  
  21028.  
  21029.  Comments
  21030.  
  21031.  Typically, an application calls PrfQueryDefinition to retrieve current
  21032.  information about the function, changes the returned structure, and calls
  21033.  PrfChangeProgram to change the program information.
  21034.  
  21035.  You cannot change the program information for any program in a protected
  21036.  group. You can change only the visibility and the protected state.
  21037.  
  21038.  
  21039.  See Also
  21040.  
  21041.  PrfCreateGroup, PrfOpenProfile, PrfQueryDefinition
  21042.  
  21043.  
  21044.  
  21045.  
  21046.  █    PrfCloseProfile
  21047.  ────────────────────────────────────────────────────────────────────────────
  21048.  
  21049.  BOOL PrfCloseProfile  (hini)
  21050.  
  21051.  HINI  hini;                       /*initialization-file handle */
  21052.  
  21053.  
  21054.  The PrfCloseProfile function closes a profile file opened by the
  21055.  PrfOpenProfile function.
  21056.  
  21057.  
  21058.  Parameters
  21059.  
  21060.  hini  Identifies the profile file to close. The file must have been
  21061.  previously opened by using the PrfOpenProfile function.
  21062.  
  21063.  
  21064.  Return Value
  21065.  
  21066.  The return value is TRUE if the function is successful or FALSE if an error
  21067.  occurs.
  21068.  
  21069.  
  21070.  Errors
  21071.  
  21072.  Use the WinGetLastError function to retrieve the error value, which may be
  21073.  the following:
  21074.  
  21075.       PMERR_INVALID_INI_FILE_HANDLE
  21076.  
  21077.  
  21078.  
  21079.  
  21080.  
  21081.  See Also
  21082.  
  21083.  PrfOpenProfile
  21084.  
  21085.  
  21086.  █    PrfCreateGroup
  21087.  ────────────────────────────────────────────────────────────────────────────
  21088.  
  21089.  HPROGRAM PrfCreateGroup  (hini, pszTitle, fsVisible)
  21090.  
  21091.  HINI  hini;                       /*initialization-file handle */
  21092.  
  21093.  PSZ  pszTitle;                    /*pointer to group title */
  21094.  
  21095.  UCHAR  fsVisible;                 /*visibility flag */
  21096.  
  21097.  
  21098.  The PrfCreateGroup function creates a new program-group entry in Desktop
  21099.  Manager. If the program group already exists, this function returns a handle
  21100.  to that group.
  21101.  
  21102.  
  21103.  Parameters
  21104.  
  21105.  hini  Identifies the file to which the new group is added. This parameter
  21106.  can be an initialization-file handle obtained by using the PrfOpenProfile
  21107.  function, or it can be the value HINI_USERPROFILE, specifying the
  21108.  user-profile file.
  21109.  
  21110.  pszTitle  Points to the title of the new group. The maximum string size is
  21111.  defined by the MAXNAMEL constant (defined in the MS OS/2 include files).
  21112.  Strings that exceed this limit are truncated to MAXNAMEL characters. Leading
  21113.  and trailing blanks are removed. The string must contain at least one
  21114.  nonblank character and cannot contain a backslash (\e).
  21115.  
  21116.  fsVisible  Specifies the visibility of the new group. This flag can be a
  21117.  combination of the following values:
  21118.  
  21119.  Value                             Meaning
  21120.  ────────────────────────────────────────────────────────────────────────────
  21121.  
  21122.  SHE_VISIBLE                       The group is visible.
  21123.  
  21124.  SHE_INVISIBLE                     The group is invisible and cannot be
  21125.                                    viewed.
  21126.  
  21127.  SHE_UNPROTECTED                   The group is unprotected.
  21128.  
  21129.  SHE_PROTECTED                     The group is protected. Programs cannot
  21130.                                    be added or deleted from the group. .
  21131.  
  21132.  
  21133.  
  21134.  This flag can also be set or reset by using the PrfChangeProgram function.
  21135.  
  21136.  
  21137.  Return Value
  21138.  
  21139.  The return value is the group handle for the group if the function is
  21140.  successful or NULL if an error occurs.
  21141.  
  21142.  
  21143.  Errors
  21144.  
  21145.  Use the WinGetLastError function to retrieve the error value, which may be
  21146.  one of the following:
  21147.  
  21148.       PMERR_INSUFF_SPACE_TO_ADD
  21149.       PMERR_INVALID_GROUP_HANDLE
  21150.       PMERR_INVALID_TARGET_HANDLE
  21151.       PMERR_INVALID_TITLE
  21152.       PMERR_MEMORY_DEALLOCATION_ERR
  21153.       PMERR_NOT_CURRENT_PL_VERSION
  21154.       PMERR_NOT_IN_IDX
  21155.  
  21156.  
  21157.  
  21158.  
  21159.  
  21160.  Comments
  21161.  
  21162.  The new program group is empty when created. Use the PrfAddProgram function
  21163.  to add program entries to the group.
  21164.  
  21165.  The PrfCreateGroup function replaces the WinCreateGroup function used in MS
  21166.  OS/2 version 1.1.
  21167.  
  21168.  
  21169.  See Also
  21170.  
  21171.  PrfAddProgram, PrfChangeProgram, WinCreateGroup
  21172.  
  21173.  
  21174.  █    PrfDestroyGroup
  21175.  ────────────────────────────────────────────────────────────────────────────
  21176.  
  21177.  BOOL PrfDestroyGroup  (hini, hGroup)
  21178.  
  21179.  HINI  hini;                       /*initialization-file handle */
  21180.  
  21181.  HPROGRAM  hGroup;                 /*group handle */
  21182.  
  21183.  
  21184.  The PrfDestroyGroup function removes a group and all program information
  21185.  contained within that group from Desktop Manager.
  21186.  
  21187.  
  21188.  Parameters
  21189.  
  21190.  hini  Identifies the file that contains the group to remove. This parameter
  21191.  can be an initialization-file handle obtained by using the PrfOpenProfile
  21192.  function, or it can be the value HINI_USERPROFILE, specifying the
  21193.  user-profile file.
  21194.  
  21195.  hGroup  Identifies the group to be removed from Desktop Manager.
  21196.  
  21197.  
  21198.  Return Value
  21199.  
  21200.  The return value is TRUE if the function is successful or FALSE if an error
  21201.  occurs.
  21202.  
  21203.  
  21204.  Errors
  21205.  
  21206.  Use the WinGetLastError function to retrieve the error value, which may be
  21207.  one of the following:
  21208.  
  21209.       PMERR_GROUP_PROTECTED
  21210.       PMERR_INVALID_GROUP_HANDLE
  21211.       PMERR_INVALID_TARGET_HANDLE
  21212.       PMERR_MEMORY_ALLOCATION_ERR
  21213.       PMERR_MEMORY_DEALLOCATION_ERR
  21214.       PMERR_NOT_CURRENT_PL_VERSION
  21215.       PMERR_NOT_IN_IDX
  21216.  
  21217.  
  21218.  
  21219.  
  21220.  
  21221.  Comments
  21222.  
  21223.  You cannot remove a group that is protected. You can remove a group that
  21224.  contains programs.
  21225.  
  21226.  
  21227.  See Also
  21228.  
  21229.  PrfCreateGroup, PrfOpenProfile
  21230.  
  21231.  
  21232.  █    PrfOpenProfile
  21233.  ────────────────────────────────────────────────────────────────────────────
  21234.  
  21235.  HINI PrfOpenProfile  (hab, pszProfileName)
  21236.  
  21237.  HAB  hab;                         /*anchor-block handle */
  21238.  
  21239.  PSZ  pszProfileName;              /*pointer to profile name */
  21240.  
  21241.  
  21242.  The PrfOpenProfile function opens a profile file. If the profile file does
  21243.  not already exist, this function creates it. This function cannot be used to
  21244.  open the user-profile or system-profile files.
  21245.  
  21246.  
  21247.  Parameters
  21248.  
  21249.  hab  Identifies the anchor block.
  21250.  
  21251.  pszProfileName  Points to the null-terminated string that contains the fully
  21252.  qualified filename of the profile file. If no path information is included,
  21253.  the default directory for the application is used. While not required, it is
  21254.  recommended that the extension .ini be used.
  21255.  
  21256.  
  21257.  Return Value
  21258.  
  21259.  The return value is a handle to the profile file if the function is
  21260.  successful or NULL if an error occurs.
  21261.  
  21262.  
  21263.  Errors
  21264.  
  21265.  Use the WinGetLastError function to retrieve the error value, which may be
  21266.  one of the following:
  21267.  
  21268.       PMERR_CALL_NOT_EXECUTED
  21269.       PMERR_INVALID_DIRECTORY
  21270.  
  21271.  
  21272.  
  21273.  
  21274.  
  21275.  See Also
  21276.  
  21277.  PrfCloseProfile
  21278.  
  21279.  
  21280.  █    PrfQueryDefinition
  21281.  ────────────────────────────────────────────────────────────────────────────
  21282.  
  21283.  ULONG PrfQueryDefinition  (hini, hprog, pprogde, cbBuf)
  21284.  
  21285.  HINI  hini;                       /*initialization-file handle */
  21286.  
  21287.  HPROGRAM  hprog;                  /*program handle */
  21288.  
  21289.  PPROGDETAILS  pprogde;            /*address of structure for program info.
  21290.                                    */
  21291.  
  21292.  ULONG  cbBuf;                     /*length of buffer for program info. */
  21293.  
  21294.  
  21295.  The PrfQueryDefinition function retrieves information about a program or
  21296.  program group.
  21297.  
  21298.  
  21299.  Parameters
  21300.  
  21301.  hini  Identifies the file that contains the program information to retrieve.
  21302.  This parameter can be an initialization-file handle obtained by using the
  21303.  PrfOpenProfile function, or it can be the value HINI_USERPROFILE, specifying
  21304.  the user-profile file.
  21305.  
  21306.  hprog  Identifies the program or group for which information is to be
  21307.  retrieved.
  21308.  
  21309.  pprogde  Points to the buffer that receives the program or group
  21310.  information. This buffer is formatted as a PROGDETAILS structure, followed
  21311.  by various strings pointed to by the fields within the PROGDETAILS
  21312.  structure. This buffer must be large enough for both the structure and all
  21313.  strings returned by this function.
  21314.  
  21315.  The PROGDETAILS structure has the following form:
  21316.  
  21317.  typedef struct _PROGDETAILS {
  21318.      ULONG    Length;
  21319.      PROGTYPE progt;
  21320.      USHORT   pad1[3];
  21321.      PSZ      pszTitle;
  21322.      PSZ      pszExecutable;
  21323.      PSZ      pszParameters;
  21324.      PSZ      pszStartupDir;
  21325.      PSZ      pszIcon;
  21326.      PSZ      pszEnvironment;
  21327.      SWP      swpInitial;
  21328.      USHORT   pad2[5];
  21329.  } PROGDETAILS;
  21330.  
  21331.  
  21332.  
  21333.  
  21334.  For a full description, see Chapter 4, "Types, Macros, Structures."
  21335.  
  21336.  cbBuf  Specifies the size (in bytes) of the buffer pointed to by the pprogde
  21337.  parameter. If this parameter is zero, only the length of the data is
  21338.  returned and the PROGDETAILS structure is not filled in.
  21339.  
  21340.  
  21341.  Return Value
  21342.  
  21343.  The return value is the number of bytes copied to the buffer pointed to by
  21344.  the pprogde parameter if the function is successful or zero if an error
  21345.  occurs. If the cbBuf parameter is zero, the return value is the size (in
  21346.  bytes) of the required buffer pointed to by the pprogde parameter.
  21347.  
  21348.  
  21349.  Errors
  21350.  
  21351.  Use the WinGetLastError function to retrieve the error value, which may be
  21352.  one of the following:
  21353.  
  21354.       PMERR_BUFFER_TOO_SMALL
  21355.       PMERR_INVALID_PARM
  21356.       PMERR_INVALID_PIB
  21357.       PMERR_INVALID_PROGRAM_HANDLE
  21358.       PMERR_INVALID_GROUP_HANDLE
  21359.       PMERR_MEMORY_ALLOCATION_ERR
  21360.       PMERR_MEMORY_DEALLOCATION_ERR
  21361.       PMERR_NOT_CURRENT_PL_VERSION
  21362.       PMERR_NOT_IN_IDX
  21363.  
  21364.  
  21365.  
  21366.  
  21367.  
  21368.  Comments
  21369.  
  21370.  If the hprog parameter is a group handle, only the progt and pszTitle fields
  21371.  in the PROGDETAILS structure pointed to by pprogde are filled in.
  21372.  
  21373.  The PrfQueryDefinition function replaces the WinQueryDefintion function used
  21374.  in MS OS/2 version 1.1.
  21375.  
  21376.  
  21377.  Example
  21378.  
  21379.  This example calls PrfQueryDefinition to determine the size of the buffer
  21380.  needed to retrieve all of the information. It then calls DosAllocSeg to
  21381.  allocate the memory and calls PrfQueryDefinition again to retrieve all of
  21382.  the program information.
  21383.  
  21384.  SEL sel;
  21385.  ULONG cb;
  21386.  PPROGDETAILS pprogde;
  21387.  
  21388.  /* First find the size of the buffer needed. */
  21389.  
  21390.  cb = PrfQueryDefinition(HINI_USERPROFILE, hprog, NULL, 0L);
  21391.  DosAllocSeg(cb, &sel, SEG_NONSHARED);
  21392.  pprogde = MAKEP(sel, 0);
  21393.  cb = PrfQueryDefinition(HINI_USERPROFILE, hprog, pprogde, cb);
  21394.  
  21395.  
  21396.  
  21397.  
  21398.  
  21399.  See Also
  21400.  
  21401.  PrfAddProgram, PrfOpenProfile, WinQueryDefinition
  21402.  
  21403.  
  21404.  █    PrfQueryProfile
  21405.  ────────────────────────────────────────────────────────────────────────────
  21406.  
  21407.  BOOL PrfQueryProfile  (hab, pprfprofile)
  21408.  
  21409.  HAB  hab;                         /*anchor-block handle */
  21410.  
  21411.  PPRFPROFILE  pprfprofile;         /*address of structure for profile data
  21412.                                    */
  21413.  
  21414.  
  21415.  The PrfQueryProfile function retrieves the fully qualified filenames of the
  21416.  two MS OS/2 profile (initialization) files.
  21417.  
  21418.  
  21419.  Parameters
  21420.  
  21421.  hab  Identifies the anchor block.
  21422.  
  21423.  pprfprofile  Points to the PRFPROFILE structure that receives information
  21424.  about the profile filenames. The PRFPROFILE structure has the following
  21425.  form:
  21426.  
  21427.  typedef struct _PRFPROFILE {
  21428.      ULONG  cchUserName;
  21429.      PSZ    pszUserName;
  21430.      ULONG  cchSysName;
  21431.      PSZ    pszSysName;
  21432.  } PRFPROFILE;
  21433.  
  21434.  
  21435.  
  21436.  
  21437.  For a full description, see Chapter 4, "Types, Macros, Structures."
  21438.  
  21439.  
  21440.  Return Value
  21441.  
  21442.  The return value is TRUE if the function is successful or FALSE if an error
  21443.  occurs.
  21444.  
  21445.  
  21446.  Comments
  21447.  
  21448.  If either length field (cchUserName or cchSysName) of the PRFPROFILE
  21449.  structure is set to zero when calling this function, the length field is set
  21450.  to the number of bytes required to hold the corresponding filename, and that
  21451.  filename field is not filled in.
  21452.  
  21453.  
  21454.  Example
  21455.  
  21456.  This example calls PrfQueryProfile to retrieve the size of the filenames,
  21457.  allocates the memory needed for each string, and calls PrfQueryProfile again
  21458.  to retrieve the filenames.
  21459.  
  21460.  PRFPROFILE prfpro;
  21461.  SEL selUser;
  21462.  SEL selSys;
  21463.  
  21464.  prfpro.cchUserName = 0L;
  21465.  prfpro.cchSysName =  0L;
  21466.  PrfQueryProfile(hab, &prfpro);            /* gets size of filenames */
  21467.  DosAllocSeg(prfpro.cchUserName, &selUser, SEG_NONSHARED);
  21468.  DosAllocSeg(prfpro.cchSysName, &selSys, SEG_NONSHARED);
  21469.  prfpro.pszUserName = MAKEP(selUser, 0);   /* initializes pointers   */
  21470.  prfpro.pszSysName = MAKEP(selSys, 0);
  21471.  PrfQueryProfile(hab, &prfpro);
  21472.  
  21473.  
  21474.  
  21475.  
  21476.  
  21477.  See Also
  21478.  
  21479.  PrfReset
  21480.  
  21481.  
  21482.  █    PrfQueryProfileData
  21483.  ────────────────────────────────────────────────────────────────────────────
  21484.  
  21485.  BOOL PrfQueryProfileData  (hini, pszAppName, pszKeyName, pvBuf, pcbBuf)
  21486.  
  21487.  HINI  hini;                       /*initialization-file handle */
  21488.  
  21489.  PSZ  pszAppName;                  /*pointer to application name */
  21490.  
  21491.  PSZ  pszKeyName;                  /*pointer to keyname */
  21492.  
  21493.  PVOID  pvBuf;                     /*pointer to buffer */
  21494.  
  21495.  PULONG  pcbBuf;                   /*buffer length */
  21496.  
  21497.  
  21498.  The PrfQueryProfileData function retrieves binary data from the profile
  21499.  file. The location of the data is determined by the application name and
  21500.  keyname that are passed to the function.
  21501.  
  21502.  
  21503.  Parameters
  21504.  
  21505.  hini  Identifies the file to query. This parameter can be a file handle
  21506.  obtained with PrfOpenProfile or one of the following values:
  21507.  
  21508.  Value                             Meaning
  21509.  ────────────────────────────────────────────────────────────────────────────
  21510.  
  21511.  HINI_PROFILE                      Search the user profile, and if no
  21512.                                    matching entries are found, search the
  21513.                                    system profile.
  21514.  
  21515.  HINI_USERPROFILE                  Search only the user profile.
  21516.  
  21517.  HINI_SYSTEMPROFILE                Search only the system profile.
  21518.  
  21519.  
  21520.  
  21521.  pszAppName  Points to the null-terminated string that contains the
  21522.  application name. The string must be less than 1024 bytes long, including
  21523.  the terminating null character. The application name is case-sensitive. If
  21524.  pszAppName is NULL, a list of all application names in the profile specified
  21525.  by the hini parameter is returned.
  21526.  
  21527.  pszKeyName  Points to the null-terminated string that contains the keyname.
  21528.  The string must be less than 1024 bytes long, including the terminating null
  21529.  character. The keyname is case-sensitive. If pszKeyName is NULL, all
  21530.  keynames in the profile specified by the hini parameter are enumerated.
  21531.  
  21532.  pvBuf  Points to the buffer that receives the data.
  21533.  
  21534.  pcbBuf  Points to a variable. When this function is called, the variable
  21535.  specifies the size (in bytes) of the buffer pointed to by the pvBuf
  21536.  parameter. When the function returns, this variable contains the actual
  21537.  number of bytes placed in the buffer.
  21538.  
  21539.  
  21540.  Return Value
  21541.  
  21542.  The return value is TRUE if the function is successful or FALSE if an error
  21543.  occurs.
  21544.  
  21545.  
  21546.  Errors
  21547.  
  21548.  Use the WinGetLastError function to retrieve the error value, which may be
  21549.  one of the following:
  21550.  
  21551.       PMERR_INVALID_PARM
  21552.       PMERR_MEMORY_ALLOC
  21553.       PMERR_MEMORY_ALLOCATION_ERR
  21554.       PMERR_MEMORY_DEALLOCATION_ERR
  21555.  
  21556.  
  21557.  
  21558.  
  21559.  
  21560.  Comments
  21561.  
  21562.  When NULL is used in pszKeyName, if the application name specified by
  21563.  pszAppName is not found, PrfQueryProfileData returns FALSE.
  21564.  
  21565.  The size of the data can be determined by calling the PrfQueryProfileSize
  21566.  function. In cases where pvBuf points to a list of values, the value
  21567.  returned by PrfQueryProfileSize will include a NULL byte at the end of the
  21568.  list, used as a terminator.
  21569.  
  21570.  
  21571.  See Also
  21572.  
  21573.  PrfQueryProfileSize, PrfWriteProfileData, WinQueryProfileData
  21574.  
  21575.  
  21576.  █    PrfQueryProfileInt
  21577.  ────────────────────────────────────────────────────────────────────────────
  21578.  
  21579.  SHORT PrfQueryProfileInt  (hini, pszAppName, pszKeyName, sError)
  21580.  
  21581.  HINI  hini;                       /*initialization-file handle */
  21582.  
  21583.  PSZ  pszAppName;                  /*pointer to application name */
  21584.  
  21585.  PSZ  pszKeyName;                  /*pointer to keyname */
  21586.  
  21587.  SHORT  sError;                    /*value returned if keyname not found */
  21588.  
  21589.  
  21590.  The PrfQueryProfileInt function retrieves an integer from the profile file.
  21591.  
  21592.  
  21593.  Parameters
  21594.  
  21595.  hini  Identifies the file to query. This parameter can be a file handle
  21596.  obtained with PrfOpenProfile or one of the following values:
  21597.  
  21598.  Value                             Meaning
  21599.  ────────────────────────────────────────────────────────────────────────────
  21600.  
  21601.  HINI_USERPROFILE                  Search only the user profile.
  21602.  
  21603.  HINI_SYSTEMPROFILE                Search only the system profile.
  21604.  
  21605.  
  21606.  
  21607.  pszAppName  Points to the null-terminated string that contains the
  21608.  application name. The string must be less than 1024 bytes long, including
  21609.  the terminating null character. The application name is case-sensitive.
  21610.  
  21611.  pszKeyName  Points to the null-terminated string that contains the keyname.
  21612.  The string must be less than 1024 bytes long, including the terminating null
  21613.  character. The keyname is case-sensitive.
  21614.  
  21615.  sError  Specifies the error value returned if the keyname specified by the
  21616.  pszKeyName parameter cannot be found.
  21617.  
  21618.  
  21619.  Return Value
  21620.  
  21621.  The return value is the integer representation of the text string. If the
  21622.  keyname cannot be found, the return value is the error value specified by
  21623.  the sError parameter.
  21624.  
  21625.  
  21626.  Errors
  21627.  
  21628.  Use the WinGetLastError function to retrieve the error value, which may be
  21629.  one of the following:
  21630.  
  21631.       PMERR_INVALID_PARM
  21632.       PMERR_MEMORY_ALLOC
  21633.       PMERR_MEMORY_ALLOCATION_ERR
  21634.       PMERR_MEMORY_DEALLOCATION_ERR
  21635.       PMERR_NOT_IN_IDX
  21636.  
  21637.  
  21638.  
  21639.  
  21640.  
  21641.  Comments
  21642.  
  21643.  The location of the integer is determined by the application name and
  21644.  keyname passed to this function. The PrfWriteProfileString function must
  21645.  have been used previously to store the integer as a string. For example, a
  21646.  string stored as "123" would be returned as the integer 123. The string may
  21647.  contain a leading minus sign if the number is negative.
  21648.  
  21649.  
  21650.  See Also
  21651.  
  21652.  PrfQueryProfileData, PrfWriteProfileString, WinQueryProfileInt
  21653.  
  21654.  
  21655.  █    PrfQueryProfileSize
  21656.  ────────────────────────────────────────────────────────────────────────────
  21657.  
  21658.  BOOL PrfQueryProfileSize  (hini, pszAppName, pszKeyName, pcb)
  21659.  
  21660.  HINI  hini;                       /*initialization-file handle */
  21661.  
  21662.  PSZ  pszAppName;                  /*pointer to application name */
  21663.  
  21664.  PSZ  pszKeyName;                  /*pointer to keyname */
  21665.  
  21666.  PULONG  pcb;                      /*pointer to variable with data length
  21667.                                    */
  21668.  
  21669.  
  21670.  The PrfQueryProfileSize function retrieves the size of the data stored at a
  21671.  specified location in the profile file.
  21672.  
  21673.  
  21674.  Parameters
  21675.  
  21676.  hini  Identifies the file to query. This parameter can be a file handle or
  21677.  one of the following values:
  21678.  
  21679.  Value                             Meaning
  21680.  ────────────────────────────────────────────────────────────────────────────
  21681.  
  21682.  HINI_PROFILE                      Search the user profile, and if no
  21683.                                    matching entries are found, search the
  21684.                                    system profile.
  21685.  
  21686.  HINI_USERPROFILE                  Search the user profile only.
  21687.  
  21688.  HINI_SYSTEMPROFILE                Search the system profile only.
  21689.  
  21690.  
  21691.  
  21692.  pszAppName  Points to the null-terminated string that contains the
  21693.  application name. The string must be less than 1024 bytes long, including
  21694.  the terminating null character. The application name is case-sensitive. If
  21695.  pszAppName is NULL, the length returned in the variable pointed to by the
  21696.  pcb parameter is the length required to contain a list of all application
  21697.  names for the pszKeyName parameter.
  21698.  
  21699.  pszKeyName  Points to the null-terminated string that contains the keyname.
  21700.  The string must be less than 1024 bytes long, including the terminating null
  21701.  character. The keyname is case-sensitive. If pszKeyName is NULL, the length
  21702.  returned in the variable pointed to by the pcb parameter is the length
  21703.  required to contain a list of all keynames.
  21704.  
  21705.  pcb  Points to the variable that receives the length of the data. If an
  21706.  error occurs, the length is not returned.
  21707.  
  21708.  
  21709.  Return Value
  21710.  
  21711.  The return value is TRUE if the function is successful.
  21712.  
  21713.  
  21714.  Errors
  21715.  
  21716.  Use the WinGetLastError function to retrieve the error value, which may be
  21717.  one of the following:
  21718.  
  21719.       PMERR_INVALID_PARM
  21720.       PMERR_MEMORY_ALLOC
  21721.       PMERR_MEMORY_ALLOCATION_ERR
  21722.       PMERR_MEMORY_DEALLOCATION_ERR
  21723.  
  21724.  
  21725.  
  21726.  
  21727.  
  21728.  Comments
  21729.  
  21730.  The location of the data stored in the profile file is determined by the
  21731.  application name and keyname passed to this function. This function is
  21732.  typically called to determine how much memory to allocate before calling
  21733.  PrfQueryProfileData.
  21734.  
  21735.  The count returned by this function will be 1 greater than that returned by
  21736.  PrfQueryProfileData or PrfQueryProfileString in cases where these functions
  21737.  will return a list. This is due to an additional null character used as a
  21738.  terminator for the entire list.
  21739.  
  21740.  
  21741.  See Also
  21742.  
  21743.  PrfQueryProfileData, PrfQueryProfileString, WinQueryProfileSize
  21744.  
  21745.  
  21746.  █    PrfQueryProfileString
  21747.  ────────────────────────────────────────────────────────────────────────────
  21748.  
  21749.  ULONG PrfQueryProfileString  (hini, pszAppName, pszKeyName, pszError,
  21750.  pszBuf, cchBuf)
  21751.  
  21752.  HINI  hini;                       /*initialization-file handle */
  21753.  
  21754.  PSZ  pszAppName;                  /*pointer to application name */
  21755.  
  21756.  PSZ  pszKeyName;                  /*pointer to keyname */
  21757.  
  21758.  PSZ  pszError;                    /*pointer to default string */
  21759.  
  21760.  PSZ  pszBuf;                      /*pointer to buffer for string */
  21761.  
  21762.  ULONG  cchBuf;                    /*buffer size */
  21763.  
  21764.  
  21765.  The PrfQueryProfileString function retrieves a string from the profile file.
  21766.  The location of the string is determined by the application name and keyname
  21767.  passed to this function.
  21768.  
  21769.  
  21770.  Parameters
  21771.  
  21772.  hini  Identifies the file to query. This parameter can be a file handle or
  21773.  one of the following values:
  21774.  
  21775.  Value                             Meaning
  21776.  ────────────────────────────────────────────────────────────────────────────
  21777.  
  21778.  HINI_PROFILE                      Search the user profile, and if no
  21779.                                    matching entries are found, search the
  21780.                                    system profile.
  21781.  
  21782.  HINI_USERPROFILE                  Search only the user profile.
  21783.  
  21784.  HINI_SYSTEMPROFILE                Search only the system profile.
  21785.  
  21786.  
  21787.  
  21788.  pszAppName  Points to the null-terminated string that contains the
  21789.  application name. The string must be less than 1024 bytes long, including
  21790.  the terminating null character. The application name is case-sensitive. If
  21791.  pszAppName is NULL, a list of all application names in the profile specified
  21792.  by the hini parameter is returned.
  21793.  
  21794.  pszKeyName  Points to the null-terminated string that contains the keyname.
  21795.  The string must be less than 1024 bytes long, including the terminating null
  21796.  character. The keyname is case-sensitive. If pszKeyName is NULL, all
  21797.  keynames in the profile specified by the hini parameter are enumerated.
  21798.  
  21799.  pszError  Points to the null-terminated string placed in the buffer pointed
  21800.  to by pszBuf if the keyname is not found.
  21801.  
  21802.  pszBuf  Points to the buffer that receives the null-terminated string.
  21803.  
  21804.  cchBuf  Specifies the length of the buffer pointed to by the pszBuf
  21805.  parameter. If the string retrieved is longer than this value, it is
  21806.  truncated.
  21807.  
  21808.  
  21809.  Return Value
  21810.  
  21811.  The return value is the number of characters in the buffer pointed to by
  21812.  pszBuf, or zero if an error occurs.
  21813.  
  21814.  
  21815.  Errors
  21816.  
  21817.  Use the WinGetLastError function to retrieve the error value, which may be
  21818.  one of the following:
  21819.  
  21820.       PMERR_INVALID_PARM
  21821.       PMERR_MEMORY_ALLOC
  21822.       PMERR_MEMORY_ALLOCATION_ERR
  21823.       PMERR_MEMORY_DEALLOCATION_ERR
  21824.  
  21825.  
  21826.  
  21827.  
  21828.  
  21829.  Comments
  21830.  
  21831.  When NULL is used in pszKeyName and the application name specified by
  21832.  pszAppName is not found, PrfQueryProfileString returns FALSE.
  21833.  
  21834.  Application data should be stored in the user profile or an
  21835.  application-specific profile. The system profile should be used only for
  21836.  system data.
  21837.  
  21838.  
  21839.  See Also
  21840.  
  21841.  PrfWriteProfileString, WinQueryProfileString
  21842.  
  21843.  
  21844.  █    PrfQueryProgramCategory
  21845.  ────────────────────────────────────────────────────────────────────────────
  21846.  
  21847.  PROGCATEGORY PrfQueryProgramCategory  (hini, pszProgramName)
  21848.  
  21849.  HINI  hini;                       /*initialization-file handle */
  21850.  
  21851.  PSZ  pszProgramName;              /*pointer to program name */
  21852.  
  21853.  
  21854.  The PrfQueryProgramCategory function retrieves the type (category) of a
  21855.  specified program.
  21856.  
  21857.  
  21858.  Parameters
  21859.  
  21860.  hini  Identifies the file to search for program information (if the program
  21861.  type cannot be determined by searching the header of the executable file).
  21862.  This parameter can be an initialization-file handle obtained by using the
  21863.  PrfOpenProfile function, or it can be the value HINI_USERPROFILE, specifying
  21864.  the user-profile file.
  21865.  
  21866.  pszProgramName  Points to the null-terminated string that contains the name
  21867.  of the executable file for which the type is to be returned. If the string
  21868.  appears to be a fully qualified path [(that is, it contains a colon (:) in
  21869.  the second position and/or contains a backslash (\e)], the file is searched
  21870.  for in the indicated directory on the indicated drive. If neither of these
  21871.  conditions is true and the file is not in the current directory, each drive
  21872.  and directory specified in the path defined in the current program's
  21873.  environment is searched. The default extension for an executable file is
  21874.  .exe, although any extension is acceptable.
  21875.  
  21876.  
  21877.  Return Value
  21878.  
  21879.  The return value is the program category if the function is successful or
  21880.  zero if an error occurs. The program type can be one of the following
  21881.  values:
  21882.  
  21883.  Value                             Meaning
  21884.  ────────────────────────────────────────────────────────────────────────────
  21885.  
  21886.  PROG_FULLSCREEN                   Program runs only in a full-screen
  21887.                                    session.
  21888.  
  21889.  PROG_WINDOWABLEVIO                Program runs in a VIO window.
  21890.  
  21891.  PROG_PM                           Program is a Presentation Manager
  21892.                                    application.
  21893.  
  21894.  PROG_REAL                         Program is a real-mode (DOS) application.
  21895.  
  21896.  PROG_DLL                          Program is a dynamic-link module.
  21897.  
  21898.  
  21899.  
  21900.  Errors
  21901.  
  21902.  Use the WinGetLastError function to retrieve the error value, which may be
  21903.  the following:
  21904.  
  21905.      PMERR_DOS_ERROR
  21906.  
  21907.  
  21908.  
  21909.  
  21910.  
  21911.  Comments
  21912.  
  21913.  The PrfQueryProgramCategory function first calls the DosQAppType function.
  21914.  If the program type cannot be determined from this call, the profile
  21915.  specified by the hini parameter is searched.
  21916.  
  21917.  Because this function calls DosQAppType, the program type returned may not
  21918.  be the same type the user specified for the program in Desktop Manager.
  21919.  
  21920.  
  21921.  See Also
  21922.  
  21923.  DosQAppType, PrfQueryDefinition
  21924.  
  21925.  
  21926.  █    PrfQueryProgramHandle
  21927.  ────────────────────────────────────────────────────────────────────────────
  21928.  
  21929.  ULONG PrfQueryProgramHandle  (hini, pszExeName, phpga, cb, pcHandles)
  21930.  
  21931.  HINI  hini;                       /*initialization-file handle */
  21932.  
  21933.  PSZ  pszExeName;                  /*pointer to executable-file name */
  21934.  
  21935.  PHPROGARRAY  phpga;               /*address of structure for program
  21936.                                    handles */
  21937.  
  21938.  ULONG  cb;                        /*buffer size */
  21939.  
  21940.  PULONG  pcHandles;                /*pointer to variable for number of
  21941.                                    handles */,
  21942.  
  21943.  
  21944.  The PrfQueryProgramHandle function retrieves the program handles that match
  21945.  the name of a specified executable file.
  21946.  
  21947.  
  21948.  Parameters
  21949.  
  21950.  hini  Identifies the file that contains the program information to retrieve.
  21951.  This parameter can be an initialization-file handle obtained by using
  21952.  PrfOpenProfile function, or it can be the value HINI_USERPROFILE, specifying
  21953.  the user-profile file.
  21954.  
  21955.  pszExeName  Points to the fully qualified path [that is, it contains a colon
  21956.  (:) in the second position and/or contains a backslash (\e)] of the
  21957.  executable file.
  21958.  
  21959.  phpga  Points to the HPROGARRAY structure that receives the program handles,
  21960.  one for each match found. The HPROGARRAY structure has the following form:
  21961.  
  21962.  typedef struct _HPROGARRAY {
  21963.      HPROGRAM ahprog[1];
  21964.  } HPROGARRAY;
  21965.  
  21966.  
  21967.  
  21968.  
  21969.  For a full description, see Chapter 4, "Types, Macros, Structures."
  21970.  
  21971.  cb  Specifies the size (in bytes) of the buffer pointed to by the phpga
  21972.  parameter. The buffer must be large enough to hold all the program handles
  21973.  retrieved.
  21974.  
  21975.  pcHandles  Points to the variable that receives the number of program
  21976.  handles placed in the structure pointed to by the phpga parameter. If this
  21977.  value is zero when the function returns, the buffer size specified by the cb
  21978.  parameter is insufficient to hold all the program handles or an error
  21979.  occurred.
  21980.  
  21981.  
  21982.  Return Value
  21983.  
  21984.  The return value is the size (in bytes) of the required buffer if the
  21985.  function is successful. Otherwise, it is zero, indicating an error occurred
  21986.  or the filename was not found.
  21987.  
  21988.  
  21989.  Errors
  21990.  
  21991.  Use the WinGetLastError function to retrieve the error value, which may be
  21992.  one of the following:
  21993.  
  21994.       PMERR_INVALID_INI_FILE_HANDLE
  21995.       PMERR_MEMORY_DEALLOCATION_ERR
  21996.       PMERR_MEMORY_ALLOCATION_ERR
  21997.  
  21998.  
  21999.  
  22000.  
  22001.  
  22002.  Comments
  22003.  
  22004.  Typically, an application calls this function twice. The first time, the cb
  22005.  parameter is set to zero and the return value is used to determine how much
  22006.  memory must be allocated to hold the program handles. The second call
  22007.  actually retrieves the program handles.
  22008.  
  22009.  
  22010.  See Also
  22011.  
  22012.  PrfOpenProfile
  22013.  
  22014.  
  22015.  
  22016.  
  22017.  █    PrfQueryProgramTitles
  22018.  ────────────────────────────────────────────────────────────────────────────
  22019.  
  22020.  ULONG PrfQueryProgramTitles  (hini, hGroup, paprogti, cbBuf, pcTitles)
  22021.  
  22022.  HINI  hini;                       /*initialization-file handle */
  22023.  
  22024.  HPROGRAM  hGroup;                 /*handle of group */
  22025.  
  22026.  PPROGTITLE  paprogti;             /*array of structures with program info.
  22027.                                    */
  22028.  
  22029.  ULONG  cbBuf;                     /*length of buffer for array of
  22030.                                    structures */
  22031.  
  22032.  PULONG  pcTitles;                 /*pointer to variable for titles */
  22033.  
  22034.  
  22035.  The PrfQueryProgramTitles function retrieves information about programs
  22036.  within a specified group in Desktop Manager.
  22037.  
  22038.  
  22039.  Parameters
  22040.  
  22041.  hini  Identifies the file that contains the program information to retrieve.
  22042.  This parameter can be an initialization-file handle obtained by using the
  22043.  PrfOpenProfile function, or it can be the value HINI_USERPROFILE, specifying
  22044.  the user-profile file.
  22045.  
  22046.  hGroup  Identifies the group or program for which information is to be
  22047.  returned. This handle can be SGH_ROOT to retrieve information about all the
  22048.  groups in Desktop Manager.
  22049.  
  22050.  paprogti  Points to the buffer that receives an array of one or more
  22051.  PROGTITLE structures followed by the strings pointed to within the
  22052.  structures. The PROGTITLE structure has the following form:
  22053.  
  22054.  typedef struct _PROGTITLE {
  22055.      HPROGRAM hprog;
  22056.      PROGTYPE progt;
  22057.      USHORT   pad1[3];
  22058.      PSZ      pszTitle;
  22059.  } PROGTITLE;
  22060.  
  22061.  
  22062.  
  22063.  
  22064.  For a full description, see Chapter 4, "Types, Macros, Structures."
  22065.  
  22066.  cbBuf  Specifies the total length (in bytes) of the buffer pointed to by the
  22067.  paprogti parameter.
  22068.  
  22069.  pcTitles  Points to the variable that receives the count of titles.
  22070.  
  22071.  
  22072.  Return Value
  22073.  
  22074.  The return value is the size of the required buffer if the function is
  22075.  successful or zero if an error occurs.
  22076.  
  22077.  
  22078.  Errors
  22079.  
  22080.  Use the WinGetLastError function to retrieve the error value, which may be
  22081.  one of the following:
  22082.  
  22083.       PMERR_BUFFER_TOO_SMALL
  22084.       PMERR_INI_FILE_CORRUPT
  22085.       PMERR_INVALID_GROUP_HANDLE
  22086.       PMERR_INVALID_PARM
  22087.       PMERR_INVALID_TARGET_HANDLE
  22088.       PMERR_MEMORY_ALLOCATION_ERR
  22089.       PMERR_MEMORY_DEALLOCATION_ERR
  22090.       PMERR_NO_ENTRIES_IN_GROUP
  22091.       PMERR_NOT_CURRENT_PL_VERSION
  22092.       PMERR_NOT_IN_IDX
  22093.       PMERR_NO_PROGRAM_FOUND
  22094.  
  22095.  
  22096.  
  22097.  
  22098.  
  22099.  Comments
  22100.  
  22101.  Typically an application calls this function twice. The first time, the
  22102.  cbBuf parameter is set to zero. The return value is used to allocate a
  22103.  sufficient buffer. Then, the application calls the function again to
  22104.  retrieve the program titles.
  22105.  
  22106.  If a program handle is specified for the hGroup parameter, the information
  22107.  for only that instance of the program is returned.
  22108.  
  22109.  
  22110.  See Also
  22111.  
  22112.  PrfAddProgram, PrfOpenProfile, WinQueryProgramTitles
  22113.  
  22114.  
  22115.  █    PrfRemoveProgram
  22116.  ────────────────────────────────────────────────────────────────────────────
  22117.  
  22118.  BOOL PrfRemoveProgram  (hini, hProgram)
  22119.  
  22120.  HINI  hini;                       /*initialization-file handle */
  22121.  
  22122.  HPROGRAM  hProgram;               /*program handle */
  22123.  
  22124.  
  22125.  The PrfRemoveProgram function removes a program from Desktop Manager.
  22126.  
  22127.  
  22128.  Parameters
  22129.  
  22130.  hini  Identifies the file that contains the program information to remove.
  22131.  This parameter can be an initialization-file handle obtained by using the
  22132.  PrfOpenProfile function, or it can be the value HINI_USERPROFILE, specifying
  22133.  the user-profile file.
  22134.  
  22135.  hProgram  Identifies the program to remove from Desktop Manager. This
  22136.  parameter cannot be a group handle.
  22137.  
  22138.  
  22139.  Return Value
  22140.  
  22141.  The return value is TRUE if the function is successful or FALSE if an error
  22142.  occurs.
  22143.  
  22144.  
  22145.  Errors
  22146.  
  22147.  Use the WinGetLastError function to retrieve the error value, which may be
  22148.  one of the following:
  22149.  
  22150.       PMERR_GROUP_PROTECTED
  22151.       PMERR_INVALID_INI_FILE_HANDLE
  22152.       PMERR_INVALID_PIB
  22153.       PMERR_INVALID_PROGRAM_HANDLE
  22154.       PMERR_MEMORY_ALLOCATION_ERR
  22155.       PMERR_MEMORY_DEALLOCATION_ERR
  22156.  
  22157.  
  22158.  
  22159.  
  22160.  
  22161.  Comments
  22162.  
  22163.  You can remove a program from a group, even if the program is currently
  22164.  running. Only the program information in the group is removed─the program
  22165.  itself is not affected.
  22166.  
  22167.  
  22168.  See Also
  22169.  
  22170.  PrfDestroyGroup, PrfOpenProfile
  22171.  
  22172.  
  22173.  
  22174.  
  22175.  █    PrfReset
  22176.  ────────────────────────────────────────────────────────────────────────────
  22177.  
  22178.  BOOL PrfReset  (hab, pprfpro)
  22179.  
  22180.  HAB  hab;                         /*anchor-block handle */
  22181.  
  22182.  pprfpro  pprfpro;                 /*address of structure with profile data
  22183.                                    */
  22184.  
  22185.  
  22186.  The PrfReset function resets Presentation Manager by rereading the
  22187.  initialization files. This function can change which initialization files
  22188.  are to be used by the system.
  22189.  
  22190.  
  22191.  Parameters
  22192.  
  22193.  hab  Identifies the anchor block.
  22194.  
  22195.  pprfpro  Points to the PRFPROFILE structure that contains the filenames of
  22196.  the initialization files. The PRFPROFILE structure has the following form:
  22197.  
  22198.  typedef struct _PRFPROFILE {
  22199.      ULONG  cchUserName;
  22200.      PSZ    pszUserName;
  22201.      ULONG  cchSysName;
  22202.      PSZ    pszSysName;
  22203.  } PRFPROFILE;
  22204.  
  22205.  
  22206.  
  22207.  
  22208.  For a full description, see Chapter 4, "Types, Macros, Structures."
  22209.  
  22210.  
  22211.  Return Value
  22212.  
  22213.  The return value is TRUE if the function is successful or FALSE if an error
  22214.  occurs.
  22215.  
  22216.  
  22217.  Errors
  22218.  
  22219.  Use the WinGetLastError function to retrieve the error value, which may be
  22220.  one of the following:
  22221.  
  22222.        PMERR_CALL_NOT_EXECUTED
  22223.        PMERR_MEMORY_ALLOC
  22224.        PMERR_MEMORY_ALLOCATION_ERR
  22225.        PMERR_MEMORY_DEALLOCATION_ERR
  22226.        PMERR_MEMORY_SHARE
  22227.        PMERR_OPEN_QUEUE
  22228.        PMERR_WRITE_QUEUE
  22229.  
  22230.  
  22231.  
  22232.  
  22233.  
  22234.  Comments
  22235.  
  22236.  The system is reset by rereading the initialization files that are specified
  22237.  in the PRFPROFILE structure. Both initialization files must be specified
  22238.  before calling this function.
  22239.  
  22240.  If the path is not included as part of the initialization-file names, the
  22241.  current directory is used.
  22242.  
  22243.  The PrfReset function modifies the PRFPROFILE structure passed to it. Before
  22244.  you can use this structure again, you must reinitialize its values.
  22245.  
  22246.  
  22247.  See Also
  22248.  
  22249.  PrfQueryProfile
  22250.  
  22251.  
  22252.  
  22253.  
  22254.  █    PrfWriteProfileData
  22255.  ────────────────────────────────────────────────────────────────────────────
  22256.  
  22257.  BOOL PrfWriteProfileData  (hini, pszAppName, pszKeyName, pchBinaryData,
  22258.  cchData)
  22259.  
  22260.  HINI  hini;                       /*initialization-file handle */
  22261.  
  22262.  PSZ  pszAppName;                  /*pointer to application name */
  22263.  
  22264.  PSZ  pszKeyName;                  /*pointer to keyname */
  22265.  
  22266.  PVOID  pchBinaryData;             /*pointer to data in profile file */
  22267.  
  22268.  ULONG  cchData;                   /*data length */
  22269.  
  22270.  
  22271.  The PrfWriteProfileData function places binary data in the specified profile
  22272.  file. The location of the data is determined by the application name and
  22273.  keyname passed to the function. This data can then be retrieved by using the
  22274.  PrfQueryProfileData function, with the application name and keyname
  22275.  specified in the pszAppName and pszKeyName parameters of the
  22276.  PrfWriteProfileData function.
  22277.  
  22278.  
  22279.  Parameters
  22280.  
  22281.  hini  Identifies the file in which to place the binary data. This parameter
  22282.  can be a file handle or one of the following values:
  22283.  
  22284.  Value                             Meaning
  22285.  ────────────────────────────────────────────────────────────────────────────
  22286.  
  22287.  HINI_USERPROFILE                  Specifies the user profile.
  22288.  
  22289.  HINI_SYSTEMPROFILE                Specifies the system profile.
  22290.  
  22291.  
  22292.  
  22293.  pszAppName  Points to the null-terminated string that contains the
  22294.  application name. The string, including the terminating null character, must
  22295.  be less than 1024 bytes long. The application name is case-sensitive. If no
  22296.  application field in the profile file matches pszAppName, a new application
  22297.  field is created.
  22298.  
  22299.  pszKeyName  Points to the null-terminated string that contains the keyname.
  22300.  The string must be less than 1024 bytes long, including the terminating null
  22301.  character. If this parameter is NULL, all keynames and their data are
  22302.  deleted. The keyname is case-sensitive. If no keyname matches pszKeyName, a
  22303.  new keyname field is created. If the keyname already exists, the existing
  22304.  value is overwritten.
  22305.  
  22306.  pchBinaryData  Points to the binary data placed in the profile file. There
  22307.  is no explicit terminating character. If this parameter is NULL, the
  22308.  previous value associated with the pszKeyName parameter is deleted;
  22309.  otherwise, the data string becomes the value, even if its length is zero.
  22310.  The data should not exceed 64K.
  22311.  
  22312.  cchData  Specifies the size (in bytes) of the pchBinaryData parameter.
  22313.  
  22314.  
  22315.  Return Value
  22316.  
  22317.  The return value is TRUE if the function is successful or FALSE if an error
  22318.  occurs. If the profile file exists but is somehow corrupted, this function
  22319.  returns FALSE.
  22320.  
  22321.  
  22322.  Errors
  22323.  
  22324.  Use the WinGetLastError function to retrieve the error value, which may be
  22325.  one of the following:
  22326.  
  22327.       PMERR_INVALID_PARM
  22328.       PMERR_MEMORY_ALLOC
  22329.       PMERR_MEMORY_ALLOCATION_ERR
  22330.       PMERR_MEMORY_DEALLOCATION_ERR
  22331.  
  22332.  
  22333.  
  22334.  
  22335.  
  22336.  Comments
  22337.  
  22338.  The application must know the size of the stored data when it calls
  22339.  PrfQueryProfileData to retrieve the data. It can retrieve the size of the
  22340.  stored data by calling the PrfQueryProfileSize function.
  22341.  
  22342.  
  22343.  See Also
  22344.  
  22345.  PrfQueryProfileData, PrfQueryProfileSize, WinWriteProfileData
  22346.  
  22347.  
  22348.  █    PrfWriteProfileString
  22349.  ────────────────────────────────────────────────────────────────────────────
  22350.  
  22351.  BOOL PrfWriteProfileString  (hini, pszAppName, pszKeyName, pszString)
  22352.  
  22353.  HINI  hini;                       /*initialization-file handle */
  22354.  
  22355.  PSZ  pszAppName;                  /*pointer to application name */
  22356.  
  22357.  PSZ  pszKeyName;                  /*pointer to keyname */
  22358.  
  22359.  PSZ  pszString;                   /*pointer to string to write */
  22360.  
  22361.  
  22362.  The PrfWriteProfileString function places an ASCII string in the profile
  22363.  file. The location of the string is determined by the application name and
  22364.  keyname passed to the function. The string can then be retrieved by using
  22365.  the PrfQueryProfileString function, specifying the same application name and
  22366.  keyname given in the pszAppName and pszKeyName parameters of
  22367.  PrfWriteProfileString.
  22368.  
  22369.  
  22370.  Parameters
  22371.  
  22372.  hini  Identifies the file to query. This parameter can be a file handle or
  22373.  one of the following values:
  22374.  
  22375.  Value                             Meaning
  22376.  ────────────────────────────────────────────────────────────────────────────
  22377.  
  22378.  HINI_USERPROFILE                  Specifies the user profile.
  22379.  
  22380.  HINI_SYSTEMPROFILE                Specifies the system profile.
  22381.  
  22382.  
  22383.  
  22384.  pszAppName  Points to the null-terminated string that contains the
  22385.  application name. The string must be less than 1024 bytes long, including
  22386.  the terminating null character. The application name is case-sensitive. If
  22387.  no application field in the profile file matches pszAppName, a new
  22388.  application field is created.
  22389.  
  22390.  pszKeyName  Points to the null-terminated string that contains the keyname.
  22391.  The string must be less than 1024 bytes long, including the terminating null
  22392.  character. If pszKeyName is NULL, all keynames and their data are deleted.
  22393.  The keyname is case-sensitive. If no keyname matches pszKeyName, a new
  22394.  keyname field is created. If the keyname already exists, the existing value
  22395.  is overwritten.
  22396.  
  22397.  pszString  Points to the null-terminated ASCII string placed in the profile
  22398.  file. If pszString is NULL, the previous value associated with pszKeyName is
  22399.  deleted; otherwise, the ASCII string becomes the value, even if its length
  22400.  is zero. The string should not exceed 64K.
  22401.  
  22402.  
  22403.  Return Value
  22404.  
  22405.  The return value is TRUE if the function is successful or FALSE if an error
  22406.  occurs.
  22407.  
  22408.  
  22409.  Errors
  22410.  
  22411.  Use the WinGetLastError function to retrieve the error value, which may be
  22412.  one of the following:
  22413.  
  22414.       PMERR_INVALID_PARM
  22415.       PMERR_MEMORY_ALLOC
  22416.       PMERR_MEMORY_ALLOCATION_ERR
  22417.       PMERR_MEMORY_DEALLOCATION_ERR
  22418.  
  22419.  
  22420.  
  22421.  
  22422.  
  22423.  Comments
  22424.  
  22425.  User application data should be stored in either the user profile or an
  22426.  application specific profile. The system profile should be used only for
  22427.  system data, such as spooler information.
  22428.  
  22429.  
  22430.  See Also
  22431.  
  22432.  PrfQueryProfileString, WinWriteProfileString
  22433.  
  22434.  
  22435.  █    PTR_GETPTRDRAWADDRESS
  22436.  ────────────────────────────────────────────────────────────────────────────
  22437.  
  22438.  USHORT DosDevIOCtl  (pbFunctionInfo, 0L, 0x0072, 0x0003, hDevice)
  22439.  
  22440.  PBYTE  pbFunctionInfo;            /*pointer to structure for function
  22441.                                    information */
  22442.  
  22443.  HFILE  hDevice;                   /*device handle */
  22444.  
  22445.  
  22446.  The PTR_GETPTRDRAWADDRESS function retrieves the entry-point address and
  22447.  other information for the pointer-draw function (the function that draws the
  22448.  mouse pointer on the screen).
  22449.  
  22450.  
  22451.  Parameters
  22452.  
  22453.  pbFunctionInfo  Points to PTRDRAWADDRESS structure that receives the
  22454.  function information. The structure has the following form:
  22455.  
  22456.  typedef struct _PTRDRAWADDRESS {    /* ptrdaddr */
  22457.      USHORT reserved;
  22458.      PTRDRAWFUNCTION ptrdfnc;
  22459.  } PTRDRAWADDRESS;
  22460.  
  22461.  
  22462.  
  22463.  
  22464.  For a full description, see Chapter 4, "Types, Macros, Structures."
  22465.  
  22466.  hDevice  Identifies the pointing device that receives the device-control
  22467.  function. The handle must have been created previously by using the DosOpen
  22468.  function.
  22469.  
  22470.  
  22471.  Return Value
  22472.  
  22473.  The return value is zero if the function is successful or an error value if
  22474.  an error occurs.
  22475.  
  22476.  
  22477.  Comments
  22478.  
  22479.  The mouse device driver uses the pointer-draw function to update the pointer
  22480.  image on the screen, and retrieves the address and saves it to use whenever
  22481.  the pointer moves.
  22482.  
  22483.  
  22484.  See Also
  22485.  
  22486.  DosOpen
  22487.  
  22488.  
  22489.  Corrections
  22490.  
  22491.  The pbFunctionInfo parameter points to a PTRDRAWADDRESS structure, not a
  22492.  PTRDRAWFUNCTION structure.
  22493.  
  22494.  
  22495.  █    SBM_SETTHUMBSIZE
  22496.  ────────────────────────────────────────────────────────────────────────────
  22497.  
  22498.  
  22499.  SBM_SETTHUMBSIZE
  22500.  mp1 = MPFROM2SHORT((USHORT) cVisible, (USHORT) cTotal); /* items */
  22501.  mp2 = 0L;                              /* not used, must be zero */
  22502.  
  22503.  
  22504.  An application sends an SBM_SETTHUMBSIZE message to set the size of the
  22505.  slider in the scroll bar.
  22506.  
  22507.  
  22508.  Parameters
  22509.  
  22510.  cVisible  Low word of mp1. Specifies the number of visible items.
  22511.  
  22512.  cTotal  High word of mp1. Specifies the total number of items.
  22513.  
  22514.  
  22515.  Return Value
  22516.  
  22517.  The return value is always TRUE.
  22518.  
  22519.  
  22520.  Comments
  22521.  
  22522.  The SBM_SETTHUMBSIZE message is usually sent when the scroll bar is
  22523.  initialized or when the client window changes size. MS OS/2 uses the two
  22524.  parameters to calculate the percentage of data visible and thus the
  22525.  percentage of the scroll bar that the slider should occupy.
  22526.  
  22527.  
  22528.  See Also
  22529.  
  22530.  SBM_QUERYPOS, SBM_QUERYRANGE, SBM_SETPOS
  22531.  
  22532.  
  22533.  █    SCR_ALLOCLDT
  22534.  ────────────────────────────────────────────────────────────────────────────
  22535.  
  22536.  USHORT DosDevIOCtl  (psel, pvAddrInfo, 0x0070, 0x0003, hDevice)
  22537.  
  22538.  PSEL  psel;                       /*pointer to LDT selector */
  22539.  
  22540.  PVOID  pvAddrInfo;                /*pointer to structure with address info
  22541.                                    */
  22542.  
  22543.  HFILE  hDevice;                   /*device handle */
  22544.  
  22545.  
  22546.  The SCR_ALLOCLDT function allocates a logical descriptor table (LDT)
  22547.  selector for an area of memory.
  22548.  
  22549.  
  22550.  Parameters
  22551.  
  22552.  psel  Points to the logical descriptor table selector for the memory area
  22553.  specified by the LDTADDRINFO structure.
  22554.  
  22555.  pvAddrInfo  Points to the LDTADDRINFO structure that contains the address
  22556.  and size of memory for which a selector is requested.
  22557.  
  22558.  The LDTADDRINFO structure has the following form:
  22559.  
  22560.  typedef struct _LDTADDRINFO {
  22561.      PULONG  pulPhysAddr;
  22562.      USHORT  cb;
  22563.  } LDTADDRINFO;
  22564.  
  22565.  
  22566.  
  22567.  
  22568.  For a full description, see Chapter 4, "Types, Macros, Structures."
  22569.  
  22570.  hDevice  Identifies the screen device that receives the device-control
  22571.  function. This handle must have been created previously by using the DosOpen
  22572.  function.
  22573.  
  22574.  
  22575.  Return Value
  22576.  
  22577.  The return value is zero if the function is successful or the error value
  22578.  ERROR_I24_INVALID_PARAMETER if an error occurs.
  22579.  
  22580.  
  22581.  Comments
  22582.  
  22583.  Read/Write access is granted to data areas completely contained in the
  22584.  address range 0xA0000 through 0xBFFFF. Read-only access is granted to data
  22585.  areas outside this range, but inside the range 0x00000 through 0xFFFFF.
  22586.  Attempts to access any address outside this range results in an error.
  22587.  
  22588.  
  22589.  See Also
  22590.  
  22591.  SCR_ALLOCLDTOFF, SCR_DEALLOCLDT
  22592.  
  22593.  
  22594.  
  22595.  
  22596.  █    SCR_ALLOCLDTOFF
  22597.  ────────────────────────────────────────────────────────────────────────────
  22598.  
  22599.  USHORT DosDevIOCtl  (ppv, pvAddrInfo, 0x0075, 0x0003, hDevice)
  22600.  
  22601.  PVOID FAR *  ppv;                 /*pointer to variable to receive
  22602.                                    selector:offset */
  22603.  
  22604.  PVOID  pvAddrInfo;                /*pointer to structure with address info
  22605.                                    */
  22606.  
  22607.  HFILE  hDevice;                   /*device handle */
  22608.  
  22609.  
  22610.  The SCR_ALLOCLDTOFF function allocates a logical descriptor table (LDT)
  22611.  selector and offset for an area of memory.
  22612.  
  22613.  
  22614.  Parameters
  22615.  
  22616.  ppv  Points to the variable that receives the allocated selector and offset.
  22617.  
  22618.  
  22619.  pvAddrInfo  Points to the LDTADDRINFO structure that contains the address
  22620.  and size of memory for which a selector is requested.
  22621.  
  22622.  The LDTADDRINFO structure has the following form:
  22623.  
  22624.  typedef struct _LDTADDRINFO {
  22625.      PULONG  pulPhysAddr;
  22626.      USHORT  cb;
  22627.  } LDTADDRINFO;
  22628.  
  22629.  
  22630.  
  22631.  
  22632.  For a full description, see Chapter 4, "Types, Macros, Structures."
  22633.  
  22634.  hDevice  Identifies the screen device that receives the device-control
  22635.  function. This handle must have been created previously by using the DosOpen
  22636.  function.
  22637.  
  22638.  
  22639.  Return Value
  22640.  
  22641.  The return value is zero if the function is successful or the error
  22642.  ERROR_I24_INVALID_PARAMETER if an error occurs.
  22643.  
  22644.  
  22645.  Comments
  22646.  
  22647.  Read/Write access is granted to data areas completely contained in the
  22648.  address range 0xA0000 through 0xBFFFF. Read-only access is granted to data
  22649.  areas outside this range, but inside the range 0x00000 through 0xFFFFF.
  22650.  Attempts to access any address outside this range result in an error.
  22651.  
  22652.  
  22653.  See Also
  22654.  
  22655.  SCR_ALLOCLDT, SCR_DEALLOCLDT
  22656.  
  22657.  
  22658.  █    SCR_DEALLOCLDT
  22659.  ────────────────────────────────────────────────────────────────────────────
  22660.  
  22661.  USHORT DosDevIOCtl  (0L, psel, 0x0071, 0x0003, hDevice)
  22662.  
  22663.  PSEL  psel;                       /*pointer to LDT selector */
  22664.  
  22665.  HFILE  hDevice;                   /*device handle */
  22666.  
  22667.  
  22668.  The SCR_DEALLOCLDT function deallocates a logical descriptor table (LDT)
  22669.  selector previously allocated by the SCR_ALLOCLDT function or the
  22670.  SCR_ALLOCLDTOFF function.
  22671.  
  22672.  
  22673.  Parameters
  22674.  
  22675.  psel  Points to the logical descriptor table selector to be deallocated.
  22676.  
  22677.  hDevice  Identifies the screen device that receives the device-control
  22678.  function. This handle must have been created previously by using the DosOpen
  22679.  function.
  22680.  
  22681.  
  22682.  Return Value
  22683.  
  22684.  The return value is zero if the function is successful or the error value
  22685.  ERROR_I24_INVALID_PARAMETER if an error occurs.
  22686.  
  22687.  
  22688.  See Also
  22689.  
  22690.  SCR_ALLOCLDT, SCR_ALLOCLDTOFF
  22691.  
  22692.  
  22693.  █    TBM_TRACKMOVE
  22694.  ────────────────────────────────────────────────────────────────────────────
  22695.  
  22696.  
  22697.  TBM_TRACKMOVE
  22698.  mp1 = MPFROMSHORT(fs);    /* tracking options       */
  22699.  mp2 = 0L;                 /* not used, must be zero */
  22700.  
  22701.  
  22702.  An application sends a TBM_TRACKMOVE message to a title-bar window control
  22703.  to move its owner window.
  22704.  
  22705.  A WM_QUERYTRACKINFO message is first sent to the owner of the title-bar
  22706.  window control. If the return value is TRUE, the window is moved; otherwise,
  22707.  the operation terminates.
  22708.  
  22709.  
  22710.  Parameters
  22711.  
  22712.  fs  Low word of mp1. Specifies tracking options. This parameter can be a
  22713.  combination of the following values:
  22714.  
  22715.  Value                             Meaning
  22716.  ────────────────────────────────────────────────────────────────────────────
  22717.  
  22718.  TF_LEFT                           Track the left side of the rectangle.
  22719.  
  22720.  TF_TOP                            Track the top side of the rectangle.
  22721.  
  22722.  TF_RIGHT                          Track the right side of the rectangle.
  22723.  
  22724.  TF_BOTTOM                         Track the bottom side of the rectangle.
  22725.  
  22726.  TF_MOVE                           Track all sides of the rectangle.
  22727.  
  22728.  TF_SETPOINTERPOS                  Reposition the pointer according to the
  22729.                                    other options specified.
  22730.  
  22731.  TF_FIXLEFT                        Vertically center the pointer at the
  22732.                                    left of the tracking rectangle.
  22733.  
  22734.  TF_FIXTOP                         Horizontally center the pointer at the
  22735.                                    top of the tracking rectangle.
  22736.  
  22737.  TF_FIXRIGHT                       Vertically center the pointer at the
  22738.                                    right of the tracking rectangle.
  22739.  
  22740.  TF_ALLINBOUNDARY                  Perform tracking so that no part of the
  22741.                                    tracking rectangle ever falls outside
  22742.                                    the bounding rectangle.
  22743.  
  22744.  TF_FIXBOTTOM                      Horizontally center the pointer at the
  22745.                                    bottom of the tracking rectangle.
  22746.  
  22747.  TF_GRID                           Restrict tracking to the grid defined by
  22748.                                    the cxGrid and cyGrid fields.
  22749.  
  22750.  TF_PARTINBOUNDARY                 Perform tracking so that all the
  22751.                                    tracking rectangle never falls outside
  22752.                                    the bounding rectangle.
  22753.  
  22754.  TF_STANDARD                       The width, height, grid width and grid
  22755.                                    height are all multiples of border width
  22756.                                    and border height.
  22757.  
  22758.  TF_VALIDATETRACKRECT              Check the tracking rectangle against
  22759.                                    size and boundary limits and modify it
  22760.                                    to fit if necessary. No actual tracking
  22761.                                    takes place; return after validating.
  22762.  
  22763.  
  22764.  
  22765.  Return Value
  22766.  
  22767.  The return value is TRUE if the operation is successful or FALSE if an error
  22768.  occurs.
  22769.  
  22770.  
  22771.  See Also
  22772.  
  22773.  WM_QUERYTRACKINFO
  22774.  
  22775.  
  22776.  █    VioCreatePS
  22777.  ────────────────────────────────────────────────────────────────────────────
  22778.  
  22779.  USHORT VioCreatePS  (phvps, cRows, cColumns, fFormat, cAttrBytes, hvps)
  22780.  
  22781.  PHVPS  phvps;                     /*pointer to variable for
  22782.                                    presentation-space handle */
  22783.  
  22784.  SHORT  cRows;                     /*height of presentation space */
  22785.  
  22786.  SHORT  cColumns;                  /*width of presentation space */
  22787.  
  22788.  SHORT  fFormat;                   /*format of attribute byte(s) */
  22789.  
  22790.  SHORT  cAttrBytes;                /*number of attributes */
  22791.  
  22792.  HVPS  hvps;                       /*presentation-space handle */
  22793.  
  22794.  
  22795.  
  22796.  
  22797.  The VioCreatePS function creates an advanced video-input-and-output (AVIO)
  22798.  presentation space, the size of which must not exceed 64K. To determine the
  22799.  size of the presentation space, multiply the cColumns, cRows, and cAttrBytes
  22800.  parameters as follows: cColumns * cRows * (cAttrBytes + 1).
  22801.  
  22802.  
  22803.  Parameters
  22804.  
  22805.  phvps  Points to the variable that receives the presentation-space handle.
  22806.  You may use this handle in subsequent Vio functions.
  22807.  
  22808.  cRows  Specifies the height (in character cells) of the presentation space.
  22809.  
  22810.  cColumns  Specifies the width (in character cells) of the presentation
  22811.  space.
  22812.  
  22813.  fFormat  Identifies the format of the attribute byte(s) in the presentation
  22814.  space. Currently, the only defined format is zero.
  22815.  
  22816.  cAttrBytes  Specifies the number of attribute bytes per character cell in
  22817.  the presentation space. This parameter may be one of the following values:
  22818.  
  22819.  Value                             Meaning
  22820.  ────────────────────────────────────────────────────────────────────────────
  22821.  
  22822.  FORMAT_CGA                        Specifies a CGA format of two attribute
  22823.                                    bytes. The first byte contains the
  22824.                                    character value. The second byte
  22825.                                    contains bit fields that specify the
  22826.                                    background and foreground colors. Blink
  22827.                                    and intensity fields are not supported.
  22828.  
  22829.  FORMAT_4BYTE                      Specifies an extended format of four
  22830.                                    attribute bytes. The first byte contains
  22831.                                    the character value. The second byte
  22832.                                    contains bit fields that specify the
  22833.                                    background and foreground colors. The
  22834.                                    third byte contains bit fields that
  22835.                                    specify the underscore, reverse video,
  22836.                                    the background opacity, and the font
  22837.                                    identifier. The fourth byte is an extra
  22838.                                    byte to be used by programs.
  22839.  
  22840.  
  22841.  
  22842.  hvps  Identifies the AVIO presentation space. This parameter must be zero.
  22843.  
  22844.  
  22845.  Return Value
  22846.  
  22847.  The return value is zero if the function is successful. Otherwise, it is an
  22848.  error value.
  22849.  
  22850.  
  22851.  See Also
  22852.  
  22853.  VioDestroyPS
  22854.  
  22855.  
  22856.  Corrections
  22857.  
  22858.  The presentation space must not exceed 64K, not 32K as previously
  22859.  documented.
  22860.  
  22861.  The only value that may be specified for the fFormat parameter is zero. The
  22862.  two FORMAT_ constants are for the cAttrBytes parameter.
  22863.  
  22864.  
  22865.  █    VioGetBuf
  22866.  ────────────────────────────────────────────────────────────────────────────
  22867.  
  22868.  USHORT VioGetBuf  (pulLVB, pcbLVB, hvio)
  22869.  
  22870.  PULONG  pulLVB;                   /*pointer to variable for address of LVB
  22871.                                    */
  22872.  
  22873.  PUSHORT  pcbLVB;                  /*pointer to variable for length of LVB
  22874.                                    */
  22875.  
  22876.  HVIO  hvio;                       /*video handle */
  22877.  
  22878.  
  22879.  The VioGetBuf function retrieves the address of the logical video buffer
  22880.  (LVB) that contains the current character attributes for the text output of
  22881.  a process. The logical video buffer is available for text-mode screens only.
  22882.  
  22883.  
  22884.  A process can access and modify the contents of the logical video buffer at
  22885.  any time, even if the process is in the background. Changes made to the
  22886.  logical video buffer do not affect the physical screen until the process
  22887.  calls the VioShowBuf function.
  22888.  
  22889.  
  22890.  Parameters
  22891.  
  22892.  pulLVB  Points to the variable that receives the address of the logical
  22893.  video buffer.
  22894.  
  22895.  pcbLVB  Points to the variable that specifies the length (in bytes) of the
  22896.  logical video buffer. You can use the VioGetMode function to determine the
  22897.  dimensions of the buffer.
  22898.  
  22899.  hvio  Identifies an advanced video-input-and-output (AVIO) presentation
  22900.  space. For AVIO programs, this handle must have been created using the
  22901.  VioCreatePS function. For other programs, hvio must be NULL.
  22902.  
  22903.  
  22904.  Return Value
  22905.  
  22906.  The return value is zero if the function is successful. Otherwise, it is an
  22907.  error value, which may be the following:
  22908.  
  22909.       ERROR_VIO_INVALID_HANDLE
  22910.  
  22911.  
  22912.  
  22913.  
  22914.  
  22915.  Comments
  22916.  
  22917.  If the process calling VioGetBuf is in the foreground, all VIO output calls
  22918.  are written to both the physical display buffer and the logical video
  22919.  buffer.
  22920.  
  22921.  If the VioSetMode function is called following a call to VioGetBuf, the size
  22922.  of the logical video buffer is adjusted to correspond to the new mode.
  22923.  
  22924.  There is one logical video buffer per session (or presentation space, for an
  22925.  AVIO application).
  22926.  
  22927.  
  22928.  Example
  22929.  
  22930.  This example calls VioGetBuf to retrieve the address of the logical video
  22931.  buffer. It sets the character attributes in the buffer for foreground
  22932.  blinking by using the OR operator to set the high bit, then it calls the
  22933.  VioShowBuf function to display the character attributes.
  22934.  
  22935.  PBYTE pbLVB;
  22936.  USHORT cbLVB, i;
  22937.  VioGetBuf((PULONG) &pbLVB, &cbLVB, 0);
  22938.  for (i = 0; i < cbLVB; i += 2)
  22939.  
  22940.      /* OR in the high bit to make it a blinking attribute */
  22941.  
  22942.      *(pbLVB + i + 1) = *(pbLVB + i + 1) | 0x80;
  22943.  VioShowBuf(0, cbLVB, 0);           /* displays buffer     */
  22944.  
  22945.  
  22946.  
  22947.  
  22948.  
  22949.  See Also
  22950.  
  22951.  VioGetMode, VioGetPhysBuf, VioShowBuf
  22952.  
  22953.  
  22954.  Corrections
  22955.  
  22956.  This function is not a family API function.
  22957.  
  22958.  The physical and logical video buffers are not always identical.
  22959.  
  22960.  
  22961.  █    VioGetConfig
  22962.  ────────────────────────────────────────────────────────────────────────────
  22963.  
  22964.  USHORT VioGetConfig  (usConfigId, pvioin, hvio)
  22965.  
  22966.  USHORT  usConfigId;               /*configuration ID */
  22967.  
  22968.  PVIOCONFIGINFO  pvioin;           /*pointer to structure for configuration
  22969.                                    */
  22970.  
  22971.  HVIO  hvio;                       /*video handle */
  22972.  
  22973.  
  22974.  The VioGetConfig function retrieves the video-display configuration, which
  22975.  defines the type of display adapter, the type of display, and the amount of
  22976.  video memory available in the current, primary, or secondary display.
  22977.  
  22978.  The VioGetConfig function is a family API function.
  22979.  
  22980.  
  22981.  Parameters
  22982.  
  22983.  usConfigId  Specifies the display adapter to retrieve the configuration for.
  22984.  This parameter can be one of the following values:
  22985.  
  22986.  Value                             Meaning
  22987.  ────────────────────────────────────────────────────────────────────────────
  22988.  
  22989.  VIO_CONFIG_CURRENT                The current display adapter
  22990.  
  22991.  VIO_CONFIG_PRIMARY                The primary display adapter
  22992.  
  22993.  VIO_CONFIG_SECONDARY              The secondary display adapter
  22994.  
  22995.  
  22996.  
  22997.  pvioin  Points to the VIOCONFIGINFO structure that receives the display
  22998.  configuration for the primary display adapter. The VIOCONFIGINFO structure
  22999.  has the following form:
  23000.  
  23001.  typedef struct _VIOCONFIGINFO {
  23002.      USHORT cb;
  23003.      USHORT adapter;
  23004.      USHORT display;
  23005.      ULONG cbMemory;
  23006.      USHORT config;
  23007.      USHORT dd_ver;
  23008.      USHORT flags;
  23009.      ULONG hwbuf;
  23010.      ULONG maxfullbuf;
  23011.      ULONG maxpartbuf;
  23012.      USHORT adaptptr;
  23013.      USHORT dispptr;
  23014.      USHORT cwadapt;
  23015.      USHORT adaptdata[1];
  23016.      USHORT cwdisp;
  23017.      USHORT dispdata[1];
  23018.  } VIOCONFIGINFO;
  23019.  
  23020.  
  23021.  
  23022.  
  23023.  For a full description, see Chapter 4, "Types, Macros, Structures."
  23024.  
  23025.  hvio  Identifies an advanced video-input-and-output (AVIO) presentation
  23026.  space. For AVIO programs, this handle must have been created using the
  23027.  VioCreatePS function. For other programs, hvio must be NULL.
  23028.  
  23029.  
  23030.  Return Value
  23031.  
  23032.  The return value is zero if the function is successful. Otherwise, it is an
  23033.  error value, which may be one of the following:
  23034.  
  23035.       ERROR_VIO_INVALID_LENGTH
  23036.       ERROR_VIO_INVALID_PARMS
  23037.  
  23038.  
  23039.  
  23040.  
  23041.  
  23042.  Comments
  23043.  
  23044.  MS OS/2 derives the values for the adapter and display fields of the
  23045.  VIOCONFIGINFO structure for the display configuration by using various
  23046.  tests, including checking the switch settings on the card.
  23047.  
  23048.  
  23049.  Example
  23050.  
  23051.  This example calls VioGetConfig to determine whether the primary display
  23052.  type is an enhanced color display.
  23053.  
  23054.  VIOCONFIGINFO vioinConfig;
  23055.  vioinConfig.cb = sizeof(vioinConfig);     /* structure length   */
  23056.  VioGetConfig(VIO_CONFIG_PRIMARY,
  23057.      &vioinConfig,                         /* configuration data */
  23058.      0);                                   /* video handle       */
  23059.  if (vioinConfig.display == DISPLAY_EGA)
  23060.      VioWrtTTY("Enhanced color display\n\r", 24, 0);
  23061.  
  23062.  
  23063.  
  23064.  
  23065.  
  23066.  See Also
  23067.  
  23068.  VioGetMode, VioGetState
  23069.  
  23070.  
  23071.  Changes
  23072.  
  23073.  The first parameter changed from usReserved to usConfigId, allowing you to
  23074.  specify which display adapter to get the configuration information from.
  23075.  
  23076.  The VIOCONFIGINFO structure pointed to by the pvioin parameter contains
  23077.  additional fields when used in MS OS/2 versions 1.2 and later.
  23078.  
  23079.  
  23080.  █    VioGetMode
  23081.  ────────────────────────────────────────────────────────────────────────────
  23082.  
  23083.  USHORT VioGetMode  (pviomi, hvio)
  23084.  
  23085.  PVIOMODEINFO  pviomi;             /*pointer to structure for screen-mode
  23086.                                    information */
  23087.  
  23088.  HVIO  hvio;                       /*video handle */
  23089.  
  23090.  
  23091.  The VioGetMode function retrieves the current screen mode. The screen mode
  23092.  defines the display mode (text or graphics), the number of colors being used
  23093.  (2, 4, or 16), and the width and height of the screen in both character
  23094.  cells and pels.
  23095.  
  23096.  The VioGetMode function is a family API function.
  23097.  
  23098.  
  23099.  Parameters
  23100.  
  23101.  pviomi  Points to the VIOMODEINFO structure that receives the screen-mode
  23102.  information. The VIOMODEINFO structure has the following form:
  23103.  
  23104.  typedef struct _VIOMODEINFO {    /* viomi */
  23105.      USHORT cb;
  23106.      UCHAR  fbType;
  23107.      UCHAR  color;
  23108.      USHORT col;
  23109.      USHORT row;
  23110.      USHORT hres;
  23111.      USHORT vres;
  23112.      UCHAR  fmt_ID;
  23113.      UCHAR  attrib;
  23114.      ULONG  buf_addr;
  23115.      ULONG  buf_length;
  23116.      ULONG  full_length;
  23117.      ULONG  partial_length;
  23118.      PCH    ext_data_addr;
  23119.  } VIOMODEINFO;
  23120.  
  23121.  
  23122.  
  23123.  
  23124.  For a full description, see Chapter 4, "Types, Macros, Structures."
  23125.  
  23126.  hvio  This parameter must be NULL.
  23127.  
  23128.  
  23129.  Return Value
  23130.  
  23131.  The return value is zero if the function is successful. Otherwise, it is an
  23132.  error value, which may be one of the following:
  23133.  
  23134.       ERROR_VIO_INVALID_HANDLE
  23135.       ERROR_VIO_INVALID_LENGTH
  23136.  
  23137.  
  23138.  
  23139.  
  23140.  
  23141.  Comments
  23142.  
  23143.  The hvio parameter can be only NULL. This function cannot be used by an
  23144.  advanced video-input-and-output application.
  23145.  
  23146.  
  23147.  Example
  23148.  
  23149.  This example calls VioGetMode to retrieve the mode information for the
  23150.  screen.
  23151.  
  23152.  VIOMODEINFO viomi;
  23153.  viomi.cb = sizeof(viomi);
  23154.  VioGetMode(&viomi, 0);
  23155.  if (viomi.fbType == 0)
  23156.      VioWrtTTY("Monochrome display\n\r", 20, 0);
  23157.  
  23158.  
  23159.  
  23160.  
  23161.  
  23162.  See Also
  23163.  
  23164.  VioGetState, VioSetMode
  23165.  
  23166.  
  23167.  Changes
  23168.  
  23169.  The VIOMODEINFO structure pointed to by the pviomi parameter contains
  23170.  several additional fields when used in MS OS/2 versions 1.2 and later.
  23171.  
  23172.  
  23173.  Corrections
  23174.  
  23175.  The hvio parameter can be only NULL. This function cannot be used by an
  23176.  advanced video-input-and-output application.
  23177.  
  23178.  
  23179.  █    VioGetState
  23180.  ────────────────────────────────────────────────────────────────────────────
  23181.  
  23182.  USHORT VioGetState  (pvoidState, hvio)
  23183.  
  23184.  PVOID  pvoidState;                /*pointer to structure for state
  23185.                                    information */
  23186.  
  23187.  HVIO  hvio;                       /*video handle */
  23188.  
  23189.  
  23190.  The VioGetState function retrieves the current settings of the
  23191.  screen-palette registers, the overscan (border) color, the blink/background
  23192.  intensity switch, the screen color, the underline position, or the target
  23193.  display.
  23194.  
  23195.  The VioSetState function is a family API function.
  23196.  
  23197.  
  23198.  Parameters
  23199.  
  23200.  pvoidState  Points to the structure that receives the state information. The
  23201.  structure type, which depends on the request type specified in the type
  23202.  field of each structure, is one of the following: VIOPALSTATE, VIOOVERSCAN,
  23203.  VIOINTENSITY, VIOCOLORREG, VIOSETULINELOC, or VIOSETTARGET. These structures
  23204.  have the following forms:
  23205.  
  23206.  typedef struct _VIOPALSTATE {
  23207.      USHORT cb;
  23208.      USHORT type;
  23209.      USHORT iFirst;
  23210.      USHORT acolor[1];
  23211.  } VIOPALSTATE;
  23212.  
  23213.  typedef struct _VIOOVERSCAN {
  23214.      USHORT cb;
  23215.      USHORT type;
  23216.      USHORT color;
  23217.  } VIOOVERSCAN;
  23218.  
  23219.  typedef struct _VIOINTENSITY {
  23220.      USHORT cb;
  23221.      USHORT type;
  23222.      USHORT fs;
  23223.  } VIOINTENSITY;
  23224.  
  23225.  typedef struct _VIOCOLORREG {
  23226.      USHORT cb;
  23227.      USHORT type;
  23228.      USHORT firstcolorreg;
  23229.      USHORT numcolorregs;
  23230.      PCH    colorregaddr;
  23231.  } VIOCOLOR;
  23232.  
  23233.  typedef struct _VIOSETULINELOC {
  23234.      USHORT cb;
  23235.      USHORT type;
  23236.      USHORT scanline;
  23237.  } VIOUNDERLINE;
  23238.  
  23239.  typedef struct _VIOSETTARGET {
  23240.      USHORT cb;
  23241.      USHORT type;
  23242.      USHORT defaultalgorithm;
  23243.  } VIOTARGET;
  23244.  
  23245.  
  23246.  
  23247.  
  23248.  For each structure, you must set the cb and type fields before calling the
  23249.  function. Not all values for the type field are valid for all screen modes.
  23250.  
  23251.  For a full description, see Chapter 4, "Types, Macros, Structures."
  23252.  
  23253.  hvio  Identifies an advanced video-input-and-output (AVIO) presentation
  23254.  space. For AVIO programs, this handle must have been created by using the
  23255.  VioCreatePS function. For other programs, hvio must be NULL.
  23256.  
  23257.  
  23258.  Return Value
  23259.  
  23260.  The return value is zero if the function is successful. Otherwise, it is an
  23261.  error value, which may be one of the following:
  23262.  
  23263.       ERROR_VIO_INVALID_HANDLE
  23264.       ERROR_VIO_INVALID_LENGTH
  23265.  
  23266.  
  23267.  
  23268.  
  23269.  
  23270.  Example
  23271.  
  23272.  This example calls the VioGetState function to retrieve the settings for
  23273.  each of the 16 palette registers.
  23274.  
  23275.  BYTE abState[38];
  23276.  PVIOPALSTATE pviopal;
  23277.  pviopal = (PVIOPALSTATE) abState;
  23278.  pviopal->cb = sizeof(abState); /* structure size                   */
  23279.  pviopal->type = 0;             /* retrieves palette registers      */
  23280.  pviopal->iFirst = 0;           /* first palette register to return */
  23281.  VioGetState(pviopal, 0);
  23282.  
  23283.  
  23284.  
  23285.  
  23286.  
  23287.  See Also
  23288.  
  23289.  VioCreatePS, VioGetMode, VioSetState
  23290.  
  23291.  
  23292.  Changes
  23293.  
  23294.  The VIOCOLORREG, VIOSETULINELOC, and VIOSETTARGET structures have been added
  23295.  to the list of possible structures for this function.
  23296.  
  23297.  
  23298.  Corrections
  23299.  
  23300.  The VioGetState function is a family API function.
  23301.  
  23302.  
  23303.  █    VioReadCellStr
  23304.  ────────────────────────────────────────────────────────────────────────────
  23305.  
  23306.  USHORT VioReadCellStr  (pchCellString, pcb, usRow, usColumn, hvio)
  23307.  
  23308.  PCH  pchCellString;               /*pointer to buffer for string */
  23309.  
  23310.  PUSHORT  pcb;                     /*pointer to variable for string length
  23311.                                    */
  23312.  
  23313.  USHORT  usRow;                    /*starting location (row) */
  23314.  
  23315.  USHORT  usColumn;                 /*starting location (column) */
  23316.  
  23317.  HVIO  hvio;                       /*video handle */
  23318.  
  23319.  
  23320.  The VioReadCellStr function reads one or more cells (character-attribute
  23321.  combinations) from the screen, starting at the specified location. If the
  23322.  string is longer than the current line, the function continues reading at
  23323.  the beginning of the next line but does not read past the end of the screen.
  23324.  
  23325.  
  23326.  The VioReadCellStr function is a family API function.
  23327.  
  23328.  
  23329.  Parameters
  23330.  
  23331.  pchCellString  Points to the buffer that receives the cell string.
  23332.  
  23333.  pcb  Points to a variable. When this function is called, the variable
  23334.  specifies the length (in bytes) of the buffer pointed to by pchCellString.
  23335.  The length should be an even number. When the function returns, this
  23336.  variable contains the length of the cell string copied to the pchCellString
  23337.  buffer.
  23338.  
  23339.  usRow  Specifies the row at which to begin reading the cell string.
  23340.  
  23341.  usColumn  Specifies the column at which to begin reading the cell string.
  23342.  
  23343.  hvio  Identifies an advanced video-input-and-output (AVIO) presentation
  23344.  space. For AVIO programs, this handle must have been created previously
  23345.  using the VioCreatePS function. For other programs, hvio must be NULL.
  23346.  
  23347.  
  23348.  Return Value
  23349.  
  23350.  The return value is zero if the function is successful. Otherwise, it is an
  23351.  error value, which may be one of the following:
  23352.  
  23353.       ERROR_VIO_COL
  23354.       ERROR_VIO_INVALID_HANDLE
  23355.       ERROR_VIO_ROW
  23356.  
  23357.  
  23358.  
  23359.  
  23360.  
  23361.  Example
  23362.  
  23363.  This example calls VioReadCellStr to read Line 0, then calls the
  23364.  VioWrtCellStr function to write the cell string to Line 24.
  23365.  
  23366.  CHAR achCells[160];
  23367.  USHORT cb = sizeof(achCells);
  23368.  VioReadCellStr(achCells,   /* buffer for string                     */
  23369.      &cb,                   /* points to variable for string length  */
  23370.      0,                     /* starting location (row)               */
  23371.      0,                     /* starting location (column)            */
  23372.      0);                    /* video handle                          */
  23373.  VioWrtCellStr(achCells, cb, 24, 0, 0);
  23374.  
  23375.  
  23376.  
  23377.  
  23378.  
  23379.  See Also
  23380.  
  23381.  VioReadCharStr, VioWrtCellStr
  23382.  
  23383.  
  23384.  Corrections
  23385.  
  23386.  The references to cells have been changed to reflect that an attribute can
  23387.  be longer than one byte.
  23388.  
  23389.  
  23390.  █    VioScrollDn
  23391.  ────────────────────────────────────────────────────────────────────────────
  23392.  
  23393.  USHORT VioScrollDn  (usTopRow, usLeftCol, usBotRow, usRightCol, cbLines,
  23394.  pbCell, hvio)
  23395.  
  23396.  USHORT  usTopRow;                 /*top row */
  23397.  
  23398.  USHORT  usLeftCol;                /*left column */
  23399.  
  23400.  USHORT  usBotRow;                 /*bottom row */
  23401.  
  23402.  USHORT  usRightCol;               /*right column */
  23403.  
  23404.  USHORT  cbLines;                  /*number of blank lines */
  23405.  
  23406.  PBYTE  pbCell;                    /*pointer to cell to write */
  23407.  
  23408.  HVIO  hvio;                       /*video handle */
  23409.  
  23410.  
  23411.  The VioScrollDn function scrolls the current screen downward.
  23412.  
  23413.  The VioScrollDn function is a family API function.
  23414.  
  23415.  
  23416.  Parameters
  23417.  
  23418.  usTopRow  Specifies the top row of the screen area to scroll.
  23419.  
  23420.  usLeftCol  Specifies the leftmost column of the screen area to scroll.
  23421.  
  23422.  usBotRow  Specifies the bottom row of the screen area to scroll.
  23423.  
  23424.  usRightCol  Specifies the rightmost column of the screen area to scroll.
  23425.  
  23426.  cbLines  Specifies the number of lines to be inserted at the top of the
  23427.  screen area being scrolled. If this parameter is zero, no lines are
  23428.  scrolled.
  23429.  
  23430.  pbCell  Points to a character/attribute combination, called a cell, that
  23431.  fills the screen area left blank by the scrolling.
  23432.  
  23433.  hvio  Identifies an advanced video-input-and-output (AVIO) presentation
  23434.  space. For AVIO programs, this handle must have been created previously
  23435.  using the VioCreatePS function. For other programs, hvio must be NULL.
  23436.  
  23437.  
  23438.  Return Value
  23439.  
  23440.  The return value is zero if the function is successful. Otherwise, it is an
  23441.  error value, which may be one of the following:
  23442.  
  23443.       ERROR_VIO_COL
  23444.       ERROR_VIO_INVALID_HANDLE
  23445.       ERROR_VIO_ROW
  23446.  
  23447.  
  23448.  
  23449.  
  23450.  
  23451.  Comments
  23452.  
  23453.  If the usTopRow and usLeftCol parameters are zero, they identify the
  23454.  upper-left corner of the screen. If you specify a value greater than the
  23455.  maximum for usTopRow, usLeftCol, usBotRow, usRightCol, or cbLines, the
  23456.  maximum value for that parameter is used. Maximum values depend upon the
  23457.  dimensions of the screen being used.
  23458.  
  23459.  You can use the VioScrollDn function to clear the screen by setting usTopRow
  23460.  and usLeftCol to zero and usBotRow, usRightCol, and cbLines to their maximum
  23461.  values. The function clears the screen by using the character/attribute
  23462.  combination pointed to by the pbCell parameter.
  23463.  
  23464.  
  23465.  Example
  23466.  
  23467.  This example creates a cell containing the space character (0x20) and a
  23468.  white character attribute (0x07 on an EGA color monitor), and calls
  23469.  VioScrollDn to clear the screen by using this cell. By changing the
  23470.  character attribute, you could change the background color of the screen
  23471.  while clearing it at the same time (using the value 0xFFFF for usBotRow,
  23472.  usRightCol, and cbLines clears the screen).
  23473.  
  23474.  BYTE bCell[2];
  23475.  bCell[0] = 0x20;      /* space character       */
  23476.  bCell[1] = 0x07;      /* white attribute (EGA) */
  23477.  VioScrollDn(0,        /* top row               */
  23478.      0,                /* left column           */
  23479.      0xFFFF,           /* bottom row            */
  23480.      0xFFFF,           /* right column          */
  23481.      0xFFFF,           /* number of lines       */
  23482.      bCell,            /* cell to write         */
  23483.      0);               /* video handle          */
  23484.  
  23485.  
  23486.  
  23487.  
  23488.  
  23489.  See Also
  23490.  
  23491.  VioCreatePS, VioScrollLf, VioScrollRt, VioScrollUp
  23492.  
  23493.  
  23494.  Corrections
  23495.  
  23496.  The references to cells have been changed to reflect that an attribute can
  23497.  be longer than one byte.
  23498.  
  23499.  
  23500.  █    VioScrollLf
  23501.  ────────────────────────────────────────────────────────────────────────────
  23502.  
  23503.  USHORT VioScrollLf  (usTopRow, usLeftCol, usBotRow, usRightCol, cbColumns,
  23504.  pbCell, hvio)
  23505.  
  23506.  USHORT  usTopRow;                 /*top row */
  23507.  
  23508.  USHORT  usLeftCol;                /*left column */
  23509.  
  23510.  USHORT  usBotRow;                 /*bottom row */
  23511.  
  23512.  USHORT  usRightCol;               /*right column */
  23513.  
  23514.  USHORT  cbColumns;                /*number of blank columns */
  23515.  
  23516.  PBYTE  pbCell;                    /*pointer to the cell to write */
  23517.  
  23518.  HVIO  hvio;                       /*video handle */
  23519.  
  23520.  
  23521.  The VioScrollLf function scrolls the current screen toward the left.
  23522.  
  23523.  The VioScrollLf function is a family API function.
  23524.  
  23525.  
  23526.  Parameters
  23527.  
  23528.  usTopRow  Specifies the top row of the screen area to scroll.
  23529.  
  23530.  usLeftCol  Specifies the leftmost column of the screen area to scroll.
  23531.  
  23532.  usBotRow  Specifies the bottom row of the screen area to scroll.
  23533.  
  23534.  usRightCol  Specifies the rightmost column of the screen area to scroll.
  23535.  
  23536.  cbColumns  Specifies the number of columns of spaces to be inserted at the
  23537.  right. If this parameter is zero, no columns are inserted.
  23538.  
  23539.  pbCell  Points to a character/attribute combination, called a cell, that
  23540.  fills the screen area left blank by the scrolling.
  23541.  
  23542.  hvio  Identifies an advanced video-input-and-output (AVIO) presentation
  23543.  space. For AVIO programs, this handle must have been created previously
  23544.  using the VioCreatePS function. For other programs, hvio must be NULL.
  23545.  
  23546.  
  23547.  Return Value
  23548.  
  23549.  The return value is zero if the function is successful. Otherwise, it is an
  23550.  error value, which may be one of the following:
  23551.  
  23552.       ERROR_VIO_COL
  23553.       ERROR_VIO_INVALID_HANDLE
  23554.       ERROR_VIO_ROW
  23555.  
  23556.  
  23557.  
  23558.  
  23559.  
  23560.  Comments
  23561.  
  23562.  If the usTopRow and usLeftCol parameters are zero, they identify the
  23563.  upper-left corner of the screen. If you specify a value greater than the
  23564.  maximum for usTopRow, usLeftCol, usBotRow, usRightCol, or cbColumns, the
  23565.  maximum value for that parameter is used. Maximum values depend upon the
  23566.  dimensions of the screen being used.
  23567.  
  23568.  You can use the VioScrollLf function to clear the screen by setting usTopRow
  23569.  and usLeftCol to zero and usBotRow, usRightCol, and cbColumns to their
  23570.  maximum values. The function clears the screen by using the
  23571.  character/attribute combination pointed to by the pbCell parameter.
  23572.  
  23573.  
  23574.  Example
  23575.  
  23576.  This example calls VioScrollLf to fill the last ten columns at the right of
  23577.  the screen with red hearts on a black background (a value of 0xFFFF is used
  23578.  for usBotRow and usRightCol).
  23579.  
  23580.  BYTE bCell[2];
  23581.  bCell[0] = 0x03;     /* heart character     */
  23582.  bCell[1] = 0x04;     /* red attribute (EGA) */
  23583.  VioScrollLf(0,       /* top row             */
  23584.      0,               /* left column         */
  23585.      0xFFFF,          /* bottom row          */
  23586.      0xFFFF,          /* right column        */
  23587.      10,              /* columns             */
  23588.      bCell,           /* cell to write       */
  23589.      0);              /* video handle        */
  23590.  
  23591.  
  23592.  
  23593.  
  23594.  
  23595.  See Also
  23596.  
  23597.  VioCreatePS, VioScrollDn, VioScrollRt, VioScrollUp
  23598.  
  23599.  
  23600.  Corrections
  23601.  
  23602.  The references to cells have been changed to reflect that an attribute can
  23603.  be longer than one byte.
  23604.  
  23605.  
  23606.  █    VioScrollRt
  23607.  ────────────────────────────────────────────────────────────────────────────
  23608.  
  23609.  USHORT VioScrollRt  (usTopRow, usLeftCol, usBotRow, usRightCol, cbColumns,
  23610.  pbCell, hvio)
  23611.  
  23612.  USHORT  usTopRow;                 /*top row */
  23613.  
  23614.  USHORT  usLeftCol;                /*left column */
  23615.  
  23616.  USHORT  usBotRow;                 /*bottom row */
  23617.  
  23618.  USHORT  usRightCol;               /*right column */
  23619.  
  23620.  USHORT  cbColumns;                /*number of blank columns */
  23621.  
  23622.  PBYTE  pbCell;                    /*pointer to cell to write */
  23623.  
  23624.  HVIO  hvio;                       /*video handle */
  23625.  
  23626.  
  23627.  The VioScrollRt function scrolls the current screen toward the right.
  23628.  
  23629.  The VioScrollRt function is a family API function.
  23630.  
  23631.  
  23632.  Parameters
  23633.  
  23634.  usTopRow  Specifies the top row of the screen area to scroll.
  23635.  
  23636.  usLeftCol  Specifies the leftmost column of the screen area to scroll.
  23637.  
  23638.  usBotRow  Specifies the bottom row of the screen area to scroll.
  23639.  
  23640.  usRightCol  Specifies the rightmost column of the screen area to scroll.
  23641.  
  23642.  cbColumns  Specifies the number of columns of spaces to be inserted at the
  23643.  left. If this parameter is zero, no columns are inserted.
  23644.  
  23645.  pbCell  Points to a character/attribute combination, called a cell, that
  23646.  fills the screen area left blank by the scrolling.
  23647.  
  23648.  hvio  Identifies an advanced video-input-and-output (AVIO) presentation
  23649.  space. For AVIO programs, this handle must have been created previously
  23650.  using the VioCreatePS function. For other programs, hvio must be NULL.
  23651.  
  23652.  
  23653.  Return Value
  23654.  
  23655.  The return value is zero if the function is successful. Otherwise, it is an
  23656.  error value, which may be one of the following:
  23657.  
  23658.       ERROR_VIO_COL
  23659.       ERROR_VIO_INVALID_HANDLE
  23660.       ERROR_VIO_ROW
  23661.  
  23662.  
  23663.  
  23664.  
  23665.  
  23666.  Comments
  23667.  
  23668.  If the usTopRow and usLeftCol parameters are zero, they identify the
  23669.  upper-left corner of the screen. If you specify a value greater than the
  23670.  maximum for usTopRow, usLeftCol, usBotRow, usRightCol, or cbColumns, the
  23671.  maximum value for that parameter is used. Maximum values depend upon the
  23672.  dimensions of the screen being used.
  23673.  
  23674.  You can use the VioScrollUp function to clear the screen by setting usTopRow
  23675.  and usLeftCol to zero and usBotRow, usRightCol, and cbColumns to their
  23676.  maximum values. The function clears the screen by using the
  23677.  character/attribute combination pointed to by the pbCell parameter.
  23678.  
  23679.  
  23680.  Example
  23681.  
  23682.  This example calls VioScrollRt to fill the first ten columns at the left of
  23683.  the screen with red hearts on a black background (a value of 0xFFFF is used
  23684.  for usBotRow and usRightCol).
  23685.  
  23686.  BYTE bCell[2];
  23687.  bCell[0] = 0x03;     /* heart character     */
  23688.  bCell[1] = 0x04;     /* red attribute (EGA) */
  23689.  VioScrollRt(0,       /* top row             */
  23690.      0,               /* left column         */
  23691.      0xFFFF,          /* bottom row          */
  23692.      0xFFFF,          /* right column        */
  23693.      10,              /* columns             */
  23694.      bCell,           /* cell to write       */
  23695.      0);              /* video handle        */
  23696.  
  23697.  
  23698.  
  23699.  
  23700.  
  23701.  See Also
  23702.  
  23703.  VioCreatePS, VioScrollDn, VioScrollLf, VioScrollUp
  23704.  
  23705.  
  23706.  Corrections
  23707.  
  23708.  The references to cells have been changed to reflect that an attribute can
  23709.  be longer than one byte.
  23710.  
  23711.  
  23712.  █    VioScrollUp
  23713.  ────────────────────────────────────────────────────────────────────────────
  23714.  
  23715.  USHORT VioScrollUp  (usTopRow, usLeftCol, usBotRow, usRightCol, cbLines,
  23716.  pbCell, hvio)
  23717.  
  23718.  USHORT  usTopRow;                 /*top row */
  23719.  
  23720.  USHORT  usLeftCol;                /*left column */
  23721.  
  23722.  USHORT  usBotRow;                 /*bottom row */
  23723.  
  23724.  USHORT  usRightCol;               /*right column */
  23725.  
  23726.  USHORT  cbLines;                  /*number of blank lines */
  23727.  
  23728.  PBYTE  pbCell;                    /*pointer to cell to write */
  23729.  
  23730.  HVIO  hvio;                       /*video handle */
  23731.  
  23732.  
  23733.  The VioScrollUp function scrolls the current screen upward.
  23734.  
  23735.  The VioScrollUp function is a family API function.
  23736.  
  23737.  
  23738.  Parameters
  23739.  
  23740.  usTopRow  Specifies the top row of the screen area to scroll.
  23741.  
  23742.  usLeftCol  Specifies the leftmost column of the screen area to scroll.
  23743.  
  23744.  usBotRow  Specifies the bottom row of the screen area to scroll.
  23745.  
  23746.  usRightCol  Specifies the rightmost column of the screen area to scroll.
  23747.  
  23748.  cbLines  Specifies the number of blank lines to insert at the bottom of the
  23749.  screen area being scrolled. If this parameter is zero, no lines are
  23750.  inserted.
  23751.  
  23752.  pbCell  Points to a character/attribute combination, called a cell, that
  23753.  fills the screen area left blank by the scrolling.
  23754.  
  23755.  hvio  Identifies an advanced video-input-and-output (AVIO) presentation
  23756.  space. For AVIO programs, this handle must have been created previously
  23757.  using the VioCreatePS function. For other programs, hvio must be NULL.
  23758.  
  23759.  
  23760.  Return Value
  23761.  
  23762.  The return value is zero if the function is successful. Otherwise, it is an
  23763.  error value, which may be one of the following:
  23764.  
  23765.       ERROR_VIO_COL
  23766.       ERROR_VIO_INVALID_HANDLE
  23767.       ERROR_VIO_ROW
  23768.  
  23769.  
  23770.  
  23771.  
  23772.  
  23773.  Comments
  23774.  
  23775.  If the usTopRow and usLeftCol parameters are zero, they identify the
  23776.  upper-left corner of the screen. If you specify a value greater than the
  23777.  maximum for usTopRow, usLeftCol, usBotRow, usRightCol, or cbLines, the
  23778.  maximum value for that parameter is used. Maximum values depend upon the
  23779.  dimensions of the screen being used.
  23780.  
  23781.  You can use the VioScrollUp function to clear the screen by setting usTopRow
  23782.  and usLeftCol to zero and usBotRow, usRightCol, and cbLines to their maximum
  23783.  values. The function clears the screen by using the character/attribute
  23784.  combination pointed to by the pbCell parameter.
  23785.  
  23786.  
  23787.  Example
  23788.  
  23789.  This example calls VioScrollUp to scroll the entire screen up (by using the
  23790.  value 0xFFFF for usBotRow, usRightCol, and cbLines) and to fill the screen
  23791.  area left blank by the scrolling with spaces on a green background (0x22 on
  23792.  an EGA color monitor).
  23793.  
  23794.  BYTE bCell[2];
  23795.  bCell[0] = 0x20;        /* space character       */
  23796.  bCell[1] = 0x22;        /* green attribute (EGA) */
  23797.  VioScrollUp(0,          /* top row               */
  23798.      0,                  /* left column           */
  23799.      0xFFFF,             /* bottom row            */
  23800.      0xFFFF,             /* right column          */
  23801.      0xFFFF,             /* number of lines       */
  23802.      bCell,              /* cell to write         */
  23803.      0);                 /* video handle          */
  23804.  VioSetCurPos(0, 0, 0);
  23805.  
  23806.  
  23807.  
  23808.  
  23809.  
  23810.  See Also
  23811.  
  23812.  VioCreatePS, VioScrollDn, VioScrollLf, VioScrollRt
  23813.  
  23814.  
  23815.  Corrections
  23816.  
  23817.  The references to cells have been changed to reflect that an attribute can
  23818.  be longer than one byte.
  23819.  
  23820.  
  23821.  █    VioSetCurType
  23822.  ────────────────────────────────────────────────────────────────────────────
  23823.  
  23824.  USHORT VioSetCurType  (pvioci, hvio)
  23825.  
  23826.  PVIOCURSORINFO  pvioci;           /*pointer to structure for cursor
  23827.                                    characteristics */
  23828.  
  23829.  HVIO  hvio;                       /*video handle */
  23830.  
  23831.  
  23832.  The VioSetCurType function sets the cursor type. The cursor is a shared
  23833.  resource for all processes in a screen group. If one process changes it, it
  23834.  is changed for all processes in the group.
  23835.  
  23836.  The VioSetCurType function is a family API function.
  23837.  
  23838.  
  23839.  Parameters
  23840.  
  23841.  pvioci  Points to the VIOCURSORINFO structure that specifies the
  23842.  characteristics of the cursor. The VIOCURSORINFO structure has the following
  23843.  form:
  23844.  
  23845.  typedef struct _VIOCURSORINFO {
  23846.      USHORT yStart;
  23847.      USHORT cEnd;
  23848.      USHORT cx;
  23849.      USHORT attr;
  23850.  } VIOCURSORINFO;
  23851.  
  23852.  
  23853.  
  23854.  
  23855.  For a full description, see Chapter 4, "Types, Macros, Structures."
  23856.  
  23857.  hvio  Identifies an advanced video-input-and-output (AVIO) presentation
  23858.  space. For AVIO programs, this handle must have been created previously by
  23859.  using the VioCreatePS function. For other programs, hvio must be NULL.
  23860.  
  23861.  
  23862.  Return Value
  23863.  
  23864.  The return value is zero if the function is successful. Otherwise, it is an
  23865.  error value, which may be one of the following:
  23866.  
  23867.      ERROR_VIO_INVALID_HANDLE
  23868.      ERROR_VIO_WIDTH
  23869.  
  23870.  
  23871.  
  23872.  
  23873.  
  23874.  Comments
  23875.  
  23876.  The yStart and cEnd fields of the VIOCURSORINFO structure can be set to
  23877.  values that are independent of the number of scan lines in the character
  23878.  cell. If you specify percentages for these values, MS OS/2 calculates the
  23879.  beginning and ending scan lines by multiplying the specified percentage by
  23880.  the number of scan lines in the character cell and rounding the total to the
  23881.  nearest scan line. Percentages are specified as a number in the range 0
  23882.  through -100. For example, if yStart is set to -90 and cEnd is set to -100,
  23883.  the cursor occupies the bottom 10 percent of the character cell.
  23884.  
  23885.  
  23886.  Example
  23887.  
  23888.  This example calls the VioSetCurType function to set the current cursor type
  23889.  to a block cursor with 14 scan lines.
  23890.  
  23891.  VIOCURSORINFO vioci;
  23892.  vioci.yStart = 0;      /* beginning scan line for cursor */
  23893.  vioci.cEnd = 13;       /* ending scan line, zero-based   */
  23894.  vioci.cx = 0;          /* default width, one character   */
  23895.  vioci.attr = 0;        /* normal attribute               */
  23896.  VioSetCurType(&vioci, 0);
  23897.  
  23898.  
  23899.  
  23900.  
  23901.  
  23902.  See Also
  23903.  
  23904.  VioCreatePS, VioGetCurType, VioSetCurPos
  23905.  
  23906.  
  23907.  Changes
  23908.  
  23909.  The yStart and cEnd fields of the VIOCURSORINFO structure can be set to
  23910.  values that are independent of the number of scan lines in the character
  23911.  cell. If you specify percentages for these values, MS OS/2 calculates the
  23912.  beginning and ending scan lines by multiplying the specified percentage by
  23913.  the number of scan lines in the character cell and rounding the total to the
  23914.  nearest scan line. Percentages are specified as a number in the range 0
  23915.  through -100. For example, if yStart is set to -90 and cEnd is set to -100,
  23916.  the cursor occupies the bottom 10 percent of the character cell.
  23917.  
  23918.  
  23919.  █    VioSetMode
  23920.  ────────────────────────────────────────────────────────────────────────────
  23921.  
  23922.  USHORT VioSetMode  (pviomi, hvio)
  23923.  
  23924.  PVIOMODEINFO  pviomi;             /*pointer to structure for screen mode
  23925.                                    */
  23926.  
  23927.  HVIO  hvio;                       /*video handle */
  23928.  
  23929.  
  23930.  The VioSetMode function sets the screen mode. The screen mode defines the
  23931.  display mode (text or graphics), the number of colors being used (2, 4, or
  23932.  16), and the width and height of the screen in both character cells and
  23933.  pels. VioSetMode also initializes the cursor position and type but does not
  23934.  clear the screen.
  23935.  
  23936.  The VioSetMode function is a family API function.
  23937.  
  23938.  
  23939.  Parameters
  23940.  
  23941.  pviomi  Points to the VIOMODEINFO structure that specifies the screen mode.
  23942.  The VIOMODEINFO structure has the following form:
  23943.  
  23944.  typedef struct _VIOMODEINFO {    /* viomi */
  23945.      USHORT cb;
  23946.      UCHAR  fbType;
  23947.      UCHAR  color;
  23948.      USHORT col;
  23949.      USHORT row;
  23950.      USHORT hres;
  23951.      USHORT vres;
  23952.      UCHAR  fmt_ID;
  23953.      UCHAR  attrib;
  23954.      ULONG  buf_addr;
  23955.      ULONG  buf_length;
  23956.      ULONG  full_length;
  23957.      ULONG  partial_length;
  23958.      PCH    ext_data_addr;
  23959.  } VIOMODEINFO;
  23960.  
  23961.  
  23962.  
  23963.  
  23964.  For a full description, see Chapter 4, "Types, Macros, Structures."
  23965.  
  23966.  hvio  This parameter must be NULL.
  23967.  
  23968.  
  23969.  Return Value
  23970.  
  23971.  The return value is zero if the function is successful. Otherwise, it is an
  23972.  error value, which may be one of the following:
  23973.  
  23974.       ERROR_VIO_INVALID_HANDLE
  23975.       ERROR_VIO_INVALID_LENGTH
  23976.       ERROR_VIO_MODE
  23977.  
  23978.  
  23979.  
  23980.  
  23981.  
  23982.  Comments
  23983.  
  23984.  Not all screen-mode values are valid for all displays.
  23985.  
  23986.  The hvio parameter can be only NULL. This function cannot be used by an
  23987.  advanced video-input-and-output application.
  23988.  
  23989.  When VioSetMode is called from a VIO-window application (as opposed to an
  23990.  application that is running in its own screen group), it does not change the
  23991.  size of a character cell.
  23992.  
  23993.  
  23994.  Example
  23995.  
  23996.  This example calls the VioGetMode function to retrieve the current display
  23997.  mode, changes the mode, and calls VioSetMode to enable the new display mode.
  23998.  
  23999.  
  24000.  VIOMODEINFO viomi;
  24001.  viomi.cb = sizeof(viomi);
  24002.  VioGetMode(&viomi, 0);
  24003.  if (viomi.vres > 350)                          /* VGA display */
  24004.      viomi.row = (viomi.row == 50) ? 25 : 50;
  24005.  else                                           /* EGA display */
  24006.      viomi.row = (viomi.row == 43) ? 25 : 43;
  24007.  VioSetMode(&viomi, 0);
  24008.  
  24009.  
  24010.  
  24011.  
  24012.  
  24013.  See Also
  24014.  
  24015.  VioGetMode, VioSetState
  24016.  
  24017.  
  24018.  Changes
  24019.  
  24020.  The VIOMODEINFO structure pointed to by the pviomi parameter contains
  24021.  several additional fields when used in MS OS/2 versions 1.2 and later.
  24022.  
  24023.  
  24024.  Corrections
  24025.  
  24026.  The hvio parameter can be only NULL. This function cannot be used by an
  24027.  advanced video-input-and-output application.
  24028.  
  24029.  
  24030.  █    VioSetState
  24031.  ────────────────────────────────────────────────────────────────────────────
  24032.  
  24033.  USHORT VioSetState  (pvoidState, hvio)
  24034.  
  24035.  PVOID  pvoidState;                /*pointer to buffer with new state */
  24036.  
  24037.  HVIO  hvio;                       /*video handle */
  24038.  
  24039.  
  24040.  The VioSetState function sets the palette-register values, the overscan
  24041.  (border) color, the blink/background intensity, the screen color, the
  24042.  underline position, or the display adapter.
  24043.  
  24044.  The VioSetState function is a family API function.
  24045.  
  24046.  
  24047.  Parameters
  24048.  
  24049.  pvoidState  Points to the structure that contains the request type and the
  24050.  values to set. The structure type, which depends on the request type
  24051.  specified in the type field of each structure, is one of the following:
  24052.  VIOPALSTATE, VIOOVERSCAN, VIOINTENSITY, VIOCOLORREG, VIOSETULINELOC, or
  24053.  VIOSETTARGET. These structures have the following forms:
  24054.  
  24055.  typedef struct _VIOPALSTATE {
  24056.      USHORT cb;
  24057.      USHORT type;
  24058.      USHORT iFirst;
  24059.      USHORT acolor[1];
  24060.  } VIOPALSTATE;
  24061.  
  24062.  typedef struct _VIOOVERSCAN {
  24063.      USHORT cb;
  24064.      USHORT type;
  24065.      USHORT color;
  24066.  } VIOOVERSCAN;
  24067.  
  24068.  typedef struct _VIOINTENSITY {
  24069.      USHORT cb;
  24070.      USHORT type;
  24071.      USHORT fs;
  24072.  } VIOINTENSITY;
  24073.  
  24074.  typedef struct _VIOCOLORREG {
  24075.      USHORT cb;
  24076.      USHORT type;
  24077.      USHORT firstcolorreg;
  24078.      USHORT numcolorregs;
  24079.      PCH    colorregaddr;
  24080.  } VIOCOLOR;
  24081.  
  24082.  typedef struct _VIOSETULINELOC {
  24083.      USHORT cb;
  24084.      USHORT type;
  24085.      USHORT scanline;
  24086.  } VIOUNDERLINE;
  24087.  
  24088.  typedef struct _VIOSETTARGET {
  24089.      USHORT cb;
  24090.      USHORT type;
  24091.      USHORT defaultalgorithm;
  24092.  } VIOTARGET;
  24093.  
  24094.  
  24095.  
  24096.  
  24097.  Not all request-type values are valid for all screen modes.
  24098.  
  24099.  For a full description, see Chapter 4, "Types, Macros, Structures."
  24100.  
  24101.  hvio  Identifies an advanced video-input-and-output (AVIO) presentation
  24102.  space. For AVIO programs, this handle must have been created by using the
  24103.  VioCreatePS function. For other programs, hvio must be NULL.
  24104.  
  24105.  
  24106.  Return Value
  24107.  
  24108.  The return value is zero if the function is successful. Otherwise, it is an
  24109.  error value, which may be one of the following:
  24110.  
  24111.       ERROR_VIO_INVALID_HANDLE
  24112.       ERROR_VIO_INVALID_LENGTH
  24113.  
  24114.  
  24115.  
  24116.  
  24117.  
  24118.  Example
  24119.  
  24120.  This example retrieves the current settings of the palette registers,
  24121.  switches palette registers #0 and #7, and calls VioSetState to enable the
  24122.  new settings.
  24123.  
  24124.  BYTE abState[38];
  24125.  PVIOPALSTATE pviopal;
  24126.  USHORT usTmp;
  24127.  pviopal = (PVIOPALSTATE) abState;
  24128.  pviopal->cb = sizeof(abState);
  24129.  pviopal->type = 0;             /* retrieves palette registers */
  24130.  pviopal->iFirst = 0;           /* first register to retrieve  */
  24131.  VioGetState(pviopal, 0);       /* retrieves current settings  */
  24132.  usTmp = pviopal->acolor[0];    /* swaps #0 and #7             */
  24133.  pviopal->acolor[0] = pviopal->acolor[7];
  24134.  pviopal->acolor[7] = usTmp;
  24135.  VioSetState(pviopal, 0);       /* enables new settings        */
  24136.  
  24137.  
  24138.  
  24139.  
  24140.  
  24141.  See Also
  24142.  
  24143.  VioCreatePS, VioGetState, VioSetMode
  24144.  
  24145.  
  24146.  Changes
  24147.  
  24148.  The VIOCOLORREG, VIOSETULINELOC, and VIOSETTARGET structures have been added
  24149.  to the list of possible structures for this function.
  24150.  
  24151.  
  24152.  Corrections
  24153.  
  24154.  The VioSetState function is a family API function.
  24155.  
  24156.  
  24157.  █    VioShowBuf
  24158.  ────────────────────────────────────────────────────────────────────────────
  24159.  
  24160.  USHORT VioShowBuf  (offLVB, cbOutput, hvio)
  24161.  
  24162.  USHORT  offLVB;                   /*offset into logical video buffer */
  24163.  
  24164.  USHORT  cbOutput;                 /*length */
  24165.  
  24166.  HVIO  hvio;                       /*video handle */
  24167.  
  24168.  
  24169.  The VioShowBuf function updates the physical screen from the logical video
  24170.  buffer (LVB). You may use the logical video buffer to directly manipulate
  24171.  information displayed on the screen.
  24172.  
  24173.  The VioShowBuf function is a family API function.
  24174.  
  24175.  
  24176.  Parameters
  24177.  
  24178.  offLVB  Specifies the offset into the logical video buffer at which the
  24179.  screen update is to start.
  24180.  
  24181.  cbOutput  Specifies the length (in bytes) of the screen area to update.
  24182.  
  24183.  hvio  Identifies an advanced video-input-and-output (AVIO) presentation
  24184.  space. For AVIO programs, this handle must have been created using the
  24185.  VioCreatePS function. For other programs, hvio must be NULL.
  24186.  
  24187.  
  24188.  Return Value
  24189.  
  24190.  The return value is zero if the function is successful. Otherwise, it is an
  24191.  error value, which may be one of the following:
  24192.  
  24193.       ERROR_VIO_INVALID_HANDLE
  24194.       ERROR_VIO_DETACHED
  24195.  
  24196.  
  24197.  
  24198.  
  24199.  
  24200.  Comments
  24201.  
  24202.  If a background process calls VioShowBuf, the function will return
  24203.  ERROR_VIO_DETACHED.
  24204.  
  24205.  
  24206.  Example
  24207.  
  24208.  This example retrieves the address of the logical video buffer, makes
  24209.  changes to that buffer, and calls VioShowBuf to update the physical video
  24210.  buffer from the logical video buffer.
  24211.  
  24212.  PBYTE pbLVB;
  24213.  USHORT cbOutput;
  24214.  VioGetBuf((PULONG) &pbLVB, &cbOutput, 0);
  24215.      .
  24216.      .
  24217.      .
  24218.  VioShowBuf(0,         /* offset into logical video buffer */
  24219.      cbOutput,         /* length of screen area            */
  24220.      0);               /* video handle                     */
  24221.  
  24222.  
  24223.  
  24224.  
  24225.  
  24226.  See Also
  24227.  
  24228.  VioCreatePS, VioGetBuf, VioGetPhysBuf
  24229.  
  24230.  
  24231.  Corrections
  24232.  
  24233.  This function is not a family API function.
  24234.  
  24235.  
  24236.  █    VioWrtCellStr
  24237.  ────────────────────────────────────────────────────────────────────────────
  24238.  
  24239.  USHORT VioWrtCellStr  (pchCellString, cbCellString, usRow, usColumn, hvio)
  24240.  
  24241.  PCH  pchCellString;               /*pointer to cell string */
  24242.  
  24243.  USHORT  cbCellString;             /*length of string */
  24244.  
  24245.  USHORT  usRow;                    /*starting position (row) */
  24246.  
  24247.  USHORT  usColumn;                 /*starting position (column) */
  24248.  
  24249.  HVIO  hvio;                       /*video handle */
  24250.  
  24251.  
  24252.  The VioWrtCellStr function writes a cell string to the screen. A cell string
  24253.  is one or more character/attribute combinations. A character/attribute
  24254.  combination defines the character to be written and the character attribute
  24255.  by which it is displayed.
  24256.  
  24257.  If the string is longer than the current line, the function continues
  24258.  writing it at the beginning of the next line, but does not write past the
  24259.  end of the screen.
  24260.  
  24261.  The VioWrtCellStr function is a family API function.
  24262.  
  24263.  
  24264.  Parameters
  24265.  
  24266.  pchCellString  Points to the cell string to write.
  24267.  
  24268.  cbCellString  Specifies the length (in bytes) of the cell string. The length
  24269.  should be an even number.
  24270.  
  24271.  usRow  Specifies the row at which to start writing the cell string.
  24272.  
  24273.  usColumn  Specifies the column at which to start writing the cell string.
  24274.  
  24275.  hvio  Identifies an advanced video-input-and-output (AVIO) presentation
  24276.  space. For AVIO programs, this handle must have been created previously
  24277.  using the VioCreatePS function. For other programs, hvio must be NULL.
  24278.  
  24279.  
  24280.  Return Value
  24281.  
  24282.  The return value is zero if the function is successful. Otherwise, it is an
  24283.  error value, which may be one of the following:
  24284.  
  24285.       ERROR_VIO_COL
  24286.       ERROR_VIO_INVALID_HANDLE
  24287.       ERROR_VIO_ROW
  24288.  
  24289.  
  24290.  
  24291.  
  24292.  
  24293.  Example
  24294.  
  24295.  This example calls the VioWrtCellStr function to display the string "Hello
  24296.  World!" using 12 different attributes.
  24297.  
  24298.  CHAR achCellString[] = "H\1e\2l\3l\4o\5 \6W\7o\10r\11l\13d\14!";
  24299.      .
  24300.      .
  24301.      .
  24302.  VioWrtCellStr(achCellString,      /* character/attribute string */
  24303.      sizeof(achCellString),        /* length of string           */
  24304.      10,                           /* row                        */
  24305.      35,                           /* column                     */
  24306.      0);                           /* video handle               */
  24307.  
  24308.  
  24309.  
  24310.  
  24311.  
  24312.  See Also
  24313.  
  24314.  VioCreatePS, VioReadCellStr, VioWrtCharStr, VioWrtTTY
  24315.  
  24316.  
  24317.  Corrections
  24318.  
  24319.  The references to cells have been changed to reflect that an attribute can
  24320.  be longer than one byte.
  24321.  
  24322.  
  24323.  █    VioWrtNCell
  24324.  ────────────────────────────────────────────────────────────────────────────
  24325.  
  24326.  USHORT VioWrtNCell  (pbCell, cb, usRow, usColumn, hvio)
  24327.  
  24328.  PBYTE  pbCell;                    /*pointer to cell to write */
  24329.  
  24330.  USHORT  cb;                       /*number of times to write */
  24331.  
  24332.  USHORT  usRow;                    /*starting position (row) */
  24333.  
  24334.  USHORT  usColumn;                 /*starting position (column) */
  24335.  
  24336.  HVIO  hvio;                       /*video handle */
  24337.  
  24338.  
  24339.  The VioWrtNCell function writes a cell to the screen a specified number of
  24340.  times. A cell (also called a character/attribute combination) consists of an
  24341.  unsigned byte value that specifies the character and one or more unsigned
  24342.  byte values that specify the attribute to be written.
  24343.  
  24344.  If the number of times that a cell is repeated is greater than the screen
  24345.  width, the VioWrtNCell function continues writing the cell at the beginning
  24346.  of the next line but does not write past the end of the screen.
  24347.  
  24348.  The VioWrtNCell function is a family API function.
  24349.  
  24350.  
  24351.  Parameters
  24352.  
  24353.  pbCell  Points to the cell to write.
  24354.  
  24355.  cb  Specifies the number of times to write the cell.
  24356.  
  24357.  usRow  Specifies the row at which to start writing the cell.
  24358.  
  24359.  usColumn  Specifies the column at which to start writing the cell.
  24360.  
  24361.  hvio  Identifies an advanced video-input-and-output (AVIO) presentation
  24362.  space. For AVIO programs, this handle must have been created previously
  24363.  using the VioCreatePS function. For other programs, hvio must be NULL.
  24364.  
  24365.  
  24366.  Return Value
  24367.  
  24368.  The return value is zero if the function is successful. Otherwise, it is an
  24369.  error value, which may be one of the following:
  24370.  
  24371.       ERROR_VIO_COL
  24372.       ERROR_VIO_INVALID_HANDLE
  24373.       ERROR_VIO_ROW
  24374.  
  24375.  
  24376.  
  24377.  
  24378.  
  24379.  Example
  24380.  
  24381.  This example calls the VioWrtNCell function to fill the screen with green
  24382.  capital letter A's (on an EGA color monitor).
  24383.  
  24384.  BYTE abCell[2];        /* character/attribute pair */
  24385.  abCell[0] = 'A';       /* character (letter A)     */
  24386.  abCell[1] = 0x02;      /* attribute (green)        */
  24387.  VioWrtNCell(abCell,    /* address of attribute     */
  24388.      80 * 25,           /* number of cells to write */
  24389.      0,                 /* row                      */
  24390.      0,                 /* column                   */
  24391.      0);                /* video handle             */
  24392.  
  24393.  
  24394.  
  24395.  
  24396.  
  24397.  See Also
  24398.  
  24399.  VioCreatePS, VioWrtNChar
  24400.  
  24401.  
  24402.  Corrections
  24403.  
  24404.  The references to cells have been changed to reflect that an attribute can
  24405.  be longer than one byte.
  24406.  
  24407.  
  24408.  █    WinAddProgram
  24409.  ────────────────────────────────────────────────────────────────────────────
  24410.  
  24411.  
  24412.  
  24413.  The WinAddProgram function provides compatibility with MS OS/2 version 1.1.
  24414.  Applications intended exclusively for MS OS/2 versions 1.2 and later should
  24415.  use the PrfAddProgram function.
  24416.  
  24417.  
  24418.  
  24419.  
  24420.  █    WinAssociateHelpInstance
  24421.  ────────────────────────────────────────────────────────────────────────────
  24422.  
  24423.  BOOL WinAssociateHelpInstance  (hwndHelpInstance, hwndApp)
  24424.  
  24425.  HWND  hwndHelpInstance;           /*handle of help instance */
  24426.  
  24427.  HWND  hwndApp;                    /*application-window handle */
  24428.  
  24429.  
  24430.  The WinAssociateHelpInstance function associates a help instance with a
  24431.  specified application window.
  24432.  
  24433.  
  24434.  Parameters
  24435.  
  24436.  hwndHelpInstance  Identifies the help instance. This handle must have been
  24437.  previously created by using the WinCreateHelpInstance function. If this
  24438.  parameter is NULL, the association (if any) between the help instance and
  24439.  the window is removed.
  24440.  
  24441.  hwndApp  Identifies the application window with which the help instance is
  24442.  associated.
  24443.  
  24444.  
  24445.  Return Value
  24446.  
  24447.  The return value is TRUE if the function is successful or FALSE if an error
  24448.  occurs.
  24449.  
  24450.  
  24451.  Errors
  24452.  
  24453.  Use the WinGetLastError function to retrieve the error value, which may be
  24454.  one of the following:
  24455.  
  24456.       HMERR_INVALID_ASSOC_HELP_INST
  24457.       HMERR_INVALID_HELP_INSTANCE_HDL
  24458.       HMERR_NO_FRAME_WND_IN_CHAIN
  24459.       HMERR_INVALID_ASSOC_APP_WND
  24460.  
  24461.  
  24462.  
  24463.  
  24464.  
  24465.  Comments
  24466.  
  24467.  A help instance can be associated with any application window that has a
  24468.  frame, but the help instance should contain help information relating to
  24469.  this application window and the windows in its window chain.
  24470.  
  24471.  
  24472.  See Also
  24473.  
  24474.  WinCreateHelpInstance
  24475.  
  24476.  
  24477.  
  24478.  
  24479.  █    WinBroadcastMsg
  24480.  ────────────────────────────────────────────────────────────────────────────
  24481.  
  24482.  BOOL WinBroadcastMsg  (hwnd, msg, mp1, mp2, fs)
  24483.  
  24484.  HWND  hwnd;                       /*handle of the parent window */
  24485.  
  24486.  USHORT  msg;                      /*message */
  24487.  
  24488.  MPARAM  mp1;                      /*message parameter */
  24489.  
  24490.  MPARAM  mp2;                      /*message parameter */
  24491.  
  24492.  USHORT  fs;                       /*windows to send message to */
  24493.  
  24494.  
  24495.  The WinBroadcastMsg function broadcasts a message to multiple windows. This
  24496.  function sends or posts a message to all immediate child windows of the
  24497.  specified window.
  24498.  
  24499.  
  24500.  Parameters
  24501.  
  24502.  hwnd  Identifies the window whose immediate child windows will receive the
  24503.  message. If this parameter is HWND_DESKTOP, the function sends the message
  24504.  to all main windows on the screen.
  24505.  
  24506.  msg  Specifies the message.
  24507.  
  24508.  mp1  Specifies the first message parameter.
  24509.  
  24510.  mp2  Specifies the second message parameter.
  24511.  
  24512.  fs  Specifies which windows to send the message to, and whether the message
  24513.  should be sent or posted. The value consists of a flag from each of the
  24514.  following lists combined using the OR operator.
  24515.  
  24516.  The following list contains the values specifying which windows to broadcast
  24517.  the message to:
  24518.  
  24519.  Destination                       Meaning
  24520.  ────────────────────────────────────────────────────────────────────────────
  24521.  
  24522.  BMSG_DESCENDANTS                  Post or send the message to hwnd and all
  24523.                                    of its descendants.
  24524.  
  24525.  BMSG_FRAMEONLY                    Post or send the message to frame
  24526.                                    windows only.
  24527.  
  24528.  
  24529.  
  24530.  The following list contains the values specifying how to broadcast the
  24531.  message (send or post):
  24532.  
  24533.  Value                             Meaning
  24534.  ────────────────────────────────────────────────────────────────────────────
  24535.  
  24536.  BMSG_POST                         Post a message to all child windows of
  24537.                                    the window specified by the hwnd
  24538.                                    parameter.
  24539.  
  24540.  BMSG_POSTQUEUE                    Post a message to all threads that have
  24541.                                    a message queue. The message's hwnd
  24542.                                    parameter will be NULL.
  24543.  
  24544.  BMSG_SEND                         Send a message to all children of the
  24545.                                    window specified by the hwnd parameter.
  24546.  
  24547.  
  24548.  
  24549.  Return Value
  24550.  
  24551.  The return value is TRUE if the function is successful or FALSE if an error
  24552.  occurs.
  24553.  
  24554.  
  24555.  See Also
  24556.  
  24557.  WinPostMsg, WinSendMsg
  24558.  
  24559.  
  24560.  Corrections
  24561.  
  24562.  To broadcast a message to all windows in the system, the hwnd parameter must
  24563.  be set to HWND_DESKTOP, not to NULL.
  24564.  
  24565.  
  24566.  █    WinCreateFrameControls
  24567.  ────────────────────────────────────────────────────────────────────────────
  24568.  
  24569.  BOOL WinCreateFrameControls  (hwndFrame, pfcdata, pszTitle)
  24570.  
  24571.  HWND  hwndFrame;                  /*handle of the frame window */
  24572.  
  24573.  PFRAMECDATA  pfcdata;             /*address of structure */
  24574.  
  24575.  PSZ  pszTitle;                    /*address of title-bar string */
  24576.  
  24577.  
  24578.  The WinCreateFrameControls function creates standard frame controls for a
  24579.  specified window. This function is used when the standard frame controls are
  24580.  needed for a nonstandard window; for example, with a window with a class
  24581.  other than WC_FRAME.
  24582.  
  24583.  
  24584.  Parameters
  24585.  
  24586.  hwndFrame  Identifies the frame window that becomes the parent and owner
  24587.  window of all the frame controls created.
  24588.  
  24589.  pfcdata  Points to the FRAMECDATA structure that contains information about
  24590.  the frame controls that are to be created. The FRAMECDATA structure has the
  24591.  following form:
  24592.  
  24593.  typedef struct _FRAMECDATA {
  24594.      USHORT cb;
  24595.      ULONG   flCreateFlags;
  24596.      HMODULE hmodResources;
  24597.      USHORT  idResources;
  24598.  } FRAMECDATA;
  24599.  
  24600.  
  24601.  
  24602.  
  24603.  For a full description, see Chapter 4, "Types, Macros, Structures."
  24604.  
  24605.  pszTitle  Points to a null-terminated string displayed in a title-bar
  24606.  control.
  24607.  
  24608.  
  24609.  Return Value
  24610.  
  24611.  The return value is TRUE if the function is successful or FALSE if an error
  24612.  occurs.
  24613.  
  24614.  
  24615.  See Also
  24616.  
  24617.  WinCreateWindow
  24618.  
  24619.  
  24620.  Corrections
  24621.  
  24622.  The syntax incorrectly listed an hmod parameter. This function has only
  24623.  three parameters, not four.
  24624.  
  24625.  
  24626.  █    WinCreateGroup
  24627.  ────────────────────────────────────────────────────────────────────────────
  24628.  
  24629.  
  24630.  
  24631.  The WinCreateGroup function provides compatibility with MS OS/2 versions 1.1
  24632.  and earlier. Applications intended exclusively for MS OS/2 versions 1.2 and
  24633.  later should use the PrfCreateGroup function.
  24634.  
  24635.  
  24636.  █    WinCreateHelpInstance
  24637.  ────────────────────────────────────────────────────────────────────────────
  24638.  
  24639.  HWND WinCreateHelpInstance  (hab, phmInitStructure)
  24640.  
  24641.  HAB  hab;                         /*anchor-block handle */
  24642.  
  24643.  PHELPINIT  phmInitStructure;      /*pointer to help structure */
  24644.  
  24645.  
  24646.  The WinCreateHelpInstance function creates a help instance. A help instance
  24647.  is an "object" window that process help requests from the application and
  24648.  the user.
  24649.  
  24650.  
  24651.  Parameters
  24652.  
  24653.  hab  Identifies the application anchor block. It must have been previous
  24654.  creating using the WinInitialize function.
  24655.  
  24656.  phmInitStructure  Points to the HELPINIT structure. The HELPINIT structure
  24657.  has the following form:
  24658.  
  24659.  typedef struct _HELPINIT {
  24660.      USHORT     cBytes;
  24661.      ULONG      ulReturnCode;
  24662.      PSZ        pszTutorialName;
  24663.      PHELPTABLE phtHelpTable;
  24664.      HMODULE    hmodHelpTableModule;
  24665.      HMODULE    hmodAccelActionBarModule;
  24666.      USHORT     idAccelTable;
  24667.      USHORT     idActionBar;
  24668.      PSZ        pszHelpWindowTitle;
  24669.      USHORT     usShowPanelId;
  24670.      PSZ        pszHelpLibraryName;
  24671.  } HELPINIT;
  24672.  
  24673.  
  24674.  
  24675.  
  24676.  For a full description, see Chapter 4, "Types, Macros, Structures."
  24677.  
  24678.  
  24679.  Return Value
  24680.  
  24681.  The return value is the handle of the help instance created if the function
  24682.  is successful or NULL if an error occurs.
  24683.  
  24684.  
  24685.  See Also
  24686.  
  24687.  WinCreateHelpTable, WinDestroyHelpInstance, WinInitialize, WinLoadHelpTable
  24688.  
  24689.  
  24690.  █    WinCreateHelpTable
  24691.  ────────────────────────────────────────────────────────────────────────────
  24692.  
  24693.  BOOL WinCreateHelpTable  (hwndHelpInstance, phtHelpTable)
  24694.  
  24695.  HWND  hwndHelpInstance;           /*handle of help instance */
  24696.  
  24697.  PHELPTABLE  phtHelpTable;         /*pointer to structure with help table
  24698.                                    */
  24699.  
  24700.  
  24701.  The WinCreateHelpTable function replaces the existing help table (if any)
  24702.  with the help table pointed to by phtHelpTable.
  24703.  
  24704.  
  24705.  Parameters
  24706.  
  24707.  hwndHelpInstance  Identifies the help instance. It must have been previously
  24708.  created using the WinCreateHelpInstance function.
  24709.  
  24710.  phtHelpTable  Points to a HELPTABLE structure containing window and
  24711.  corresponding help panel IDs. The HELPTABLE structure has the following
  24712.  form:
  24713.  
  24714.  typedef struct _HELPTABLE {
  24715.      USHORT        idAppWindow;
  24716.      PHELPSUBTABLE phstHelpSubTable;
  24717.      USHORT        idExtPanel;
  24718.  } HELPTABLE;
  24719.  
  24720.  
  24721.  
  24722.  
  24723.  For a full description, see Chapter 4, "Types, Macros, Structures."
  24724.  
  24725.  
  24726.  Return Value
  24727.  
  24728.  The return value is TRUE if the function is successful or FALSE if an error
  24729.  occurs.
  24730.  
  24731.  
  24732.  Comments
  24733.  
  24734.  Applications can use this function to replace a help instance's initial help
  24735.  table or to set the table if no initial help table is given. The initial
  24736.  help table is specified in the HELPINIT structure when the help instance is
  24737.  created with the WinCreateHelpInstance function. The function replaces the
  24738.  help table without freeing any memory or resources associated with the
  24739.  initial help table.
  24740.  
  24741.  
  24742.  See Also
  24743.  
  24744.  WinCreateHelpInstance
  24745.  
  24746.  
  24747.  █    WinCreatePointerIndirect
  24748.  ────────────────────────────────────────────────────────────────────────────
  24749.  
  24750.  HPOINTER WinCreatePointerIndirect  (hwndDesktop, pptri)
  24751.  
  24752.  HWND  hwndDesktop;                /*desktop handle */
  24753.  
  24754.  PPOINTERINFO  pptri;              /*pointer to structure with bitmap */
  24755.  
  24756.  
  24757.  The WinCreatePointerIndirect function creates a pointer by using the
  24758.  POINTERINFO structure. It can create a color pointer.
  24759.  
  24760.  
  24761.  Parameters
  24762.  
  24763.  hwndDesktop  Identifies the desktop window. This parameter can be
  24764.  HWND_DESKTOP or the desktop window handle.
  24765.  
  24766.  pptri  Points to the POINTERINFO structure that contains the bitmap used to
  24767.  create the pointer image. The POINTERINFO structure has the following form:
  24768.  
  24769.  typedef struct _POINTERINFO {
  24770.      BOOL    fPointer;
  24771.      SHORT   xHotspot;
  24772.      SHORT   yHotspot;
  24773.      HBITMAP hbmPointer;
  24774.  } POINTERINFO;
  24775.  
  24776.  
  24777.  
  24778.  
  24779.  For a full description, see Chapter 4, "Types, Macros, Structures."
  24780.  
  24781.  
  24782.  Return Value
  24783.  
  24784.  The return value is the handle of the new pointer if successful or NULL if
  24785.  an error occurs.
  24786.  
  24787.  
  24788.  Comments
  24789.  
  24790.  The WinCreatePointerIndirect and WinCreatePointer functions are similar. The
  24791.  difference between them is that the WinCreatePointerIndirect function can
  24792.  create a color pointer; the WinCreatePointer function can create only a
  24793.  black-and-white pointer.
  24794.  
  24795.  
  24796.  See Also
  24797.  
  24798.  WinCreatePointer
  24799.  
  24800.  
  24801.  █    WinCreateStdWindow
  24802.  ────────────────────────────────────────────────────────────────────────────
  24803.  
  24804.  HWND WinCreateStdWindow  (hwndParent, flStyle, pflCreateFlags,
  24805.  pszClientClass, pszTitle, flClientStyle, hmod, idResources, phwndClient)
  24806.  
  24807.  HWND  hwndParent;                 /*handle of the parent window */
  24808.  
  24809.  ULONG  flStyle;                   /*frame-window style */
  24810.  
  24811.  PULONG  pflCreateFlags;           /*creation flags */
  24812.  
  24813.  PSZ  pszClientClass;              /*client-window class name */
  24814.  
  24815.  PSZ  pszTitle;                    /*address of title-bar text */
  24816.  
  24817.  ULONG  flClientStyle;             /*client-window style */
  24818.  
  24819.  HMODULE  hmod;                    /*handle of the resource module */
  24820.  
  24821.  USHORT  idResources;              /*frame-window identifier */
  24822.  
  24823.  PHWND  phwndClient;               /*address of the client-window handle */
  24824.  
  24825.  
  24826.  The WinCreateStdWindow function creates a standard frame window.
  24827.  
  24828.  
  24829.  Parameters
  24830.  
  24831.  hwndParent  Identifies the parent window. A main window is created if this
  24832.  parameter is HWND_DESKTOP or a window handle returned by the
  24833.  WinQueryDesktopWindow function. An object window is created if this
  24834.  parameter is HWND_OBJECT or a window handle returned by the
  24835.  WinQueryObjectWindow function.
  24836.  
  24837.  flStyle  Specifies the frame-window style. It can be any combination of the
  24838.  WS_ styles (see the description for flClientStyle) and the following values:
  24839.  
  24840.  
  24841.  Value                             Meaning
  24842.  ────────────────────────────────────────────────────────────────────────────
  24843.  
  24844.  FS_ACCELTABLE                     Creates an accelerator table. The table
  24845.                                    is loaded from the application's
  24846.                                    resource file. It should have the same
  24847.                                    identifier as the menu and the icon (if
  24848.                                    any).
  24849.  
  24850.  FS_BORDER                         Creates a window with a single-line
  24851.                                    border around it. The width of the
  24852.                                    border line is SV_CXBORDER and the
  24853.                                    height is SV_CYBORDER. For a description
  24854.                                    of these system values, see the
  24855.                                    "Comments" section of WinSetSysValue
  24856.                                    function.
  24857.  
  24858.  FS_DLGBORDER                      Creates a window that has a border with
  24859.                                    an inner border drawn with the active
  24860.                                    title-bar color. It is used most often
  24861.                                    by dialog boxes.
  24862.  
  24863.  FS_ICON                           The created window has an icon with the
  24864.                                    same identifier as the menu and
  24865.                                    accelerator table (if any).
  24866.  
  24867.  FS_MOUSEALIGN                     Creates a window whose position is
  24868.                                    relative to the current position of the
  24869.                                    mouse. Normally, this is used only by
  24870.                                    dialog boxes.
  24871.  
  24872.  FS_NOBYTEALIGN                    Creates a window whereby the frame
  24873.                                    window is not byte aligned. Setting this
  24874.                                    flag will decrease the performance of
  24875.                                    drawing operations to the client window.
  24876.  
  24877.  FS_NOMOVEWITHOWNER                Creates a frame window that will not
  24878.                                    move if the owner window moves.
  24879.  
  24880.  FS_SCREENALIGN                    Creates a window that is aligned with
  24881.                                    respect to the screen. Normally, this is
  24882.                                    used only by dialog boxes.
  24883.  
  24884.  FS_SHELLPOSITION                  The Presentation Manager (shell)
  24885.                                    determines the position of the window,
  24886.                                    typically in a cascaded position from
  24887.                                    the last application that started.
  24888.  
  24889.  FS_SIZEBORDER                     Creates a sizing border.
  24890.  
  24891.  FS_SYSMODAL                       Creates a system modal window. For a
  24892.                                    description of a system modal window,
  24893.                                    see the "Comments" section of the
  24894.                                    WinSetSysModalWindow function.
  24895.  
  24896.  FS_TASKLIST                       The window title is added to the Task
  24897.                                    Manager's list.
  24898.  
  24899.  FS_STANDARD                       Specifies a combination of the
  24900.                                    FS_ACCELTABLE, FS_ICON, FS_SHELLPOSITION,
  24901.                                    and FS_TASKLIST styles.
  24902.  
  24903.  
  24904.  
  24905.  pflCreateFlags  Specifies options that control how the frame window is
  24906.  created. If no options are specified, FCF_STANDARD is used. The flags may be
  24907.  any combination of the following values:
  24908.  
  24909.  Value                             Meaning
  24910.  ────────────────────────────────────────────────────────────────────────────
  24911.  
  24912.  FCF_ACCELTABLE                    Creates an accelerator table. The table
  24913.                                    is loaded from the application's
  24914.                                    resource file. It should have the same
  24915.                                    identifier as the menu and the icon (if
  24916.                                    any).
  24917.  
  24918.  FCF_BORDER                        Creates a window with a single-line
  24919.                                    border around it. The width of the
  24920.                                    border line is SV_CXBORDER and the
  24921.                                    height is SV_CYBORDER. For a description
  24922.                                    of these system values, see the
  24923.                                    "Comments" section of the WinSetSysValue
  24924.                                    function.
  24925.  
  24926.  FCF_DLGBORDER                     Creates a window that has a border with
  24927.                                    an inner border drawn with the active
  24928.                                    title-bar color. It is used most often
  24929.                                    by dialog boxes.
  24930.  
  24931.  FCF_HORZSCROLL                    Creates a horizontal scroll bar.
  24932.  
  24933.  FCF_ICON                          The created window has an icon with the
  24934.                                    same identifier as the menu and
  24935.                                    accelerator table (if any). The icon is
  24936.                                    used whenever the frame window is
  24937.                                    minimized.
  24938.  
  24939.  FCF_MAXBUTTON                     Creates a maximize button.
  24940.  
  24941.  FCF_MENU                          Creates a menu bar.
  24942.  
  24943.  FCF_MINBUTTON                     Creates a minimize button.
  24944.  
  24945.  FCF_MINMAX                        Creates a minimize and a maximize button
  24946.                                    (FCF_MINBUTTON | FCF_MAXBUTTON).
  24947.  
  24948.  FCF_MOUSEALIGN                    Creates a window whose position is
  24949.                                    relative to the current position of the
  24950.                                    mouse. Normally, this is used only by
  24951.                                    dialog boxes.
  24952.  
  24953.  FCF_NOBYTEALIGN                   Creates a window whereby the client
  24954.                                    window is not byte aligned. Setting this
  24955.                                    flag will decrease the performance of
  24956.                                    drawing operations to the client window.
  24957.  
  24958.  FCF_NOMOVEWITHOWNER               Creates a window that will not move if
  24959.                                    the owner window moves.
  24960.  
  24961.  FCF_SCREENALIGN                   Creates a window that is aligned with
  24962.                                    respect to the screen. Normally, this is
  24963.                                    used only by dialog boxes.
  24964.  
  24965.  FCF_SHELLPOSITION                 The Presentation Manager (shell)
  24966.                                    determines the position of the window,
  24967.                                    typically in a cascaded position from
  24968.                                    the last application that started.
  24969.  
  24970.  FCF_SIZEBORDER                    Creates a sizing border.
  24971.  
  24972.  FCF_SYSMENU                       Creates a system menu.
  24973.  
  24974.  FCF_SYSMODAL                      Creates a system modal window. For a
  24975.                                    description of a system modal window,
  24976.                                    see the "Comments" section of the
  24977.                                    WinSetSysModalWindow function.
  24978.  
  24979.  FCF_TASKLIST                      Adds the window to the switch list of
  24980.                                    the Task Manager.
  24981.  
  24982.  FCF_TITLEBAR                      Creates a title bar.
  24983.  
  24984.  FCF_VERTSCROLL                    Creates a vertical scroll bar.
  24985.  
  24986.  FCF_STANDARD                      Specifies a combination of the
  24987.                                    following flags:
  24988.  
  24989.                                         FCF_TITLEBAR
  24990.                                         FCF_SYSMENU
  24991.                                         FCF_MENU
  24992.                                         FCF_SIZEBORDER
  24993.                                         FCF_MINMAX
  24994.                                         FCF_ICON
  24995.                                         FCF_ACCELTABLE
  24996.                                         FCF_SHELLPOSITION
  24997.                                         FCF_TASKLIST
  24998.  
  24999.  
  25000.  pszClientClass  Points to the client-window class name. If the
  25001.  pszClientClass parameter is not a zero-length string, a client window of
  25002.  style flClientStyle and class pszClientClass is created. This parameter is
  25003.  an application-specified name (defined by the WinRegisterClass function),
  25004.  the name of a preregistered WC class, or a WC constant. If this parameter is
  25005.  NULL, no client area is created.
  25006.  
  25007.  pszTitle  Points to the title-bar text. This parameter is ignored if
  25008.  FCF_TITLEBAR is not specified in the pflCreateFlags parameter.
  25009.  
  25010.  flClientStyle  Specifies the client-window style. It can be a combination of
  25011.  one or more of the following values:
  25012.  
  25013.  Value                             Meaning
  25014.  ────────────────────────────────────────────────────────────────────────────
  25015.  
  25016.  WS_CLIPCHILDREN                   Prevents a window from painting over its
  25017.                                    child windows.
  25018.  
  25019.  WS_CLIPSIBLINGS                   Prevents a window from painting over its
  25020.                                    sibling windows. ,
  25021.  
  25022.  WS_DISABLED                       Disables mouse and keyboard input to the
  25023.                                    window. It is used to temporarily
  25024.                                    prevent the user from using the window.
  25025.  
  25026.  WS_MAXIMIZED                      Enlarges the window to the maximum size.
  25027.  
  25028.  WS_MINIMIZED                      Reduces the window to the minimum size.
  25029.  
  25030.  WS_PARENTCLIP                     Prevents a window from painting over its
  25031.                                    parent window.
  25032.  
  25033.  WS_SAVEBITS                       Saves the image under the window as a
  25034.                                    bitmap. When the window is moved or
  25035.                                    hidden, the system restores the image by
  25036.                                    copying the bits.
  25037.  
  25038.  WS_SYNCPAINT                      Causes the window to immediately receive
  25039.                                    WM_PAINT messages after a part of the
  25040.                                    window becomes invalid. Without this
  25041.                                    style, the window receives WM_PAINT
  25042.                                    messages only if no other message is
  25043.                                    waiting to be processed.
  25044.  
  25045.  WS_VISIBLE                        Makes the window visible. This window
  25046.                                    will be drawn on the screen unless
  25047.                                    overlapping windows completely obscure
  25048.                                    it. Windows without this style are
  25049.                                    hidden.
  25050.  
  25051.  
  25052.  
  25053.  This parameter is ignored if the pszClientClass parameter is a zero-length
  25054.  string.
  25055.  
  25056.  hmod  Identifies the module that contains the resource definitions. This
  25057.  parameter can be either the module handle returned by the DosLoadModule
  25058.  function or NULL for the application's module. This parameter is ignored
  25059.  unless FS_ICON, FS_ACCELTABLE, or FS_MENU is specified in the flStyle
  25060.  parameter.
  25061.  
  25062.  idResources  Identifies the frame-window identifier and the identifier
  25063.  within the resource definition of the required resource. The application
  25064.  must ensure that all resources related to one frame window have the same
  25065.  identifier value.
  25066.  
  25067.  phwndClient  Points to the variable that receives the client-window handle.
  25068.  It will be NULL if the function fails.
  25069.  
  25070.  
  25071.  Return Value
  25072.  
  25073.  The return value is the handle of the frame window, or it is NULL if an
  25074.  error occurs.
  25075.  
  25076.  
  25077.  Comments
  25078.  
  25079.  The client window created by WinCreateStdWindow does not have an owner. If
  25080.  the client window must have an owner (for example, if the client window is a
  25081.  list box), the application must call the WinSetOwner function to set the
  25082.  owner of the client window after the call to WinCreateStdWindow.
  25083.  
  25084.  
  25085.  Example
  25086.  
  25087.  This example shows a typical initialization function for a window. The
  25088.  function first registers the window class, then calls WinCreateStdWindow to
  25089.  create a standard window and returns immediately if the function fails.
  25090.  Otherwise, it continues on to do other initialization processing.
  25091.  
  25092.  Note that the FCF_STANDARD constant can be used only if you have defined all
  25093.  the resources. For example, if you use this constant and you don't have an
  25094.  accelerator table, the function will fail.
  25095.  
  25096.  CHAR szClassName[] = "Generic";          /* window class name    */
  25097.  HWND hwndClient;                         /* handle to the client */
  25098.  HWND hwndFrame;                          /* handle to the frame  */
  25099.  
  25100.  BOOL GenericInit()
  25101.  {
  25102.      ULONG flStyle;
  25103.  
  25104.      flStyle = FCF_STANDARD;
  25105.      if (!WinRegisterClass(hab, szClassName, GenericWndProc, 0L, 0))
  25106.          return (FALSE);
  25107.  
  25108.      hwndFrame = WinCreateStdWindow(HWND_DESKTOP,
  25109.          0L,                     /* frame-window style            */
  25110.          &flStyle,               /* window style                  */
  25111.          szClassName,            /* class name                    */
  25112.          "Generic Application",  /* window title                  */
  25113.          0L,                     /* default client style          */
  25114.          NULL,                   /* resource in executable file   */
  25115.          IDM_RESOURCE,           /* resource id                   */
  25116.          &hwndClient);           /* receives client window handle */
  25117.  
  25118.      if (!hwndFrame)
  25119.          return (FALSE);
  25120.      else {
  25121.          .
  25122.          . /* other initialization code */
  25123.          .
  25124.  
  25125.  
  25126.  
  25127.  
  25128.  
  25129.  See Also
  25130.  
  25131.  DosLoadModule, WinCreateWindow, WinQueryDesktopWindow, WinQueryObjectWindow,
  25132.  WinSetSysModalWindow, WinSetSysValue, WinSetWindowPos, WinSetWindowUShort
  25133.  
  25134.  
  25135.  Corrections
  25136.  
  25137.  NULL cannot be used for the hwndParent parameter.
  25138.  
  25139.  
  25140.  █    WinCreateSwitchEntry
  25141.  ────────────────────────────────────────────────────────────────────────────
  25142.  
  25143.  HSWITCH WinCreateSwitchEntry  (hab, pswctl)
  25144.  
  25145.  HAB  hab;                         /*anchor-block handle */
  25146.  
  25147.  PSWCNTRL  pswctl;                 /*pointer to structure with new entry
  25148.                                    information */
  25149.  
  25150.  
  25151.  The WinCreateSwitchEntry function creates an entry in the switch list (the
  25152.  list of running programs displayed in the Task List).
  25153.  
  25154.  
  25155.  Parameters
  25156.  
  25157.  hab  Identifies the anchor block.
  25158.  
  25159.  pswctl  Points to the SWCNTRL structure that contains information about the
  25160.  new switch-list entry. If the szSwtitle field in the SWCNTRL structure is
  25161.  NULL, the system uses the name under which the application was started.
  25162.  
  25163.  This applies only to the first call to this function for that program (since
  25164.  the program was started). Otherwise, a null entry name is invalid. The
  25165.  SWCNTRL structure has the following form:
  25166.  
  25167.  typedef struct _SWCNTRL {
  25168.      HWND     hwnd;
  25169.      HWND     hwndIcon;
  25170.      HPROGRAM hprog;
  25171.      USHORT   idProcess;
  25172.      USHORT   idSession;
  25173.      UCHAR    uchVisibility;
  25174.      UCHAR    fbJump;
  25175.      CHAR     szSwtitle[MAXNAMEL+1];
  25176.      BYTE     fReserved;
  25177.  } SWCNTRL;
  25178.  
  25179.  
  25180.  
  25181.  
  25182.  For a full description, see Chapter 4, "Types, Macros, Structures."
  25183.  
  25184.  
  25185.  Return Value
  25186.  
  25187.  The return value is a handle to the new switch-list entry, or NULL if an
  25188.  error occurs.
  25189.  
  25190.  
  25191.  Comments
  25192.  
  25193.  The WinCreateSwitchEntry and WinAddSwitchEntry functions are similar. The
  25194.  only difference between them is that WinCreateSwitchEntry takes an
  25195.  anchor-block handle as the first parameter.
  25196.  
  25197.  Leading and trailing blanks are removed from the title. The title is
  25198.  truncated to 60 characters.
  25199.  
  25200.  
  25201.  Example
  25202.  
  25203.  This example calls WinQueryWindowProcess to get the current process
  25204.  identifier (needed for the SWCNTRL structure). It then sets up the swctl
  25205.  structure and calls WinCreateSwitchEntry to add the program's name to the
  25206.  Task List.
  25207.  
  25208.  The returned handle can be used in subsequent calls to WinChangeSwitchEntry
  25209.  if the title needs to be changed.
  25210.  
  25211.  The variables swctl, hswitch, and pid should be global if your application
  25212.  will be calling the WinChangeSwitchEntry function to avoid having to set up
  25213.  the structure again.
  25214.  
  25215.  SWCNTRL swctl;
  25216.  HSWITCH hswitch;
  25217.  PID pid;
  25218.  HAB hab;
  25219.  
  25220.  hab = WinQueryAnchorBlock(hwndFrame);                /* gets anchor block */
  25221.  WinQueryWindowProcess(hwndFrame, &pid, (PTID) NULL); /* gets process id   */
  25222.  
  25223.  swctl.hwnd = hwndFrame;                        /* window handle      */
  25224.  swctl.hwndIcon = (HWND) NULL;                  /* icon handle        */
  25225.  swctl.hprog = (HPROGRAM) NULL;                 /* program handle     */
  25226.  swctl.idProcess = pid;                         /* process identifier */
  25227.  swctl.idSession = o;                           /* session identifier */
  25228.  swctl.uchVisibility = SWL_VISIBLE;             /* visibility         */
  25229.  swctl.fbJump = SWL_JUMPABLE;                   /* jump indicator     */
  25230.  swctl.szSwtitle[0] = '\0';                     /* program name       */
  25231.  
  25232.  hswitch = WinCreateSwitchEntry(hab, &swctl);
  25233.  
  25234.  
  25235.  
  25236.  
  25237.  
  25238.  See Also
  25239.  
  25240.  WinAddSwitchEntry, WinChangeSwitchEntry, WinRemoveSwitchEntry
  25241.  
  25242.  
  25243.  █    WinCreateWindow
  25244.  ────────────────────────────────────────────────────────────────────────────
  25245.  
  25246.  HWND WinCreateWindow  (hwndParent, pszClass, pszName, flStyle, x, y, cx, cy,
  25247.  hwndOwner, hwndInsertBehind, id, pCtlData, pPresParams)
  25248.  
  25249.  HWND  hwndParent;                 /*parent-window handle */
  25250.  
  25251.  PSZ  pszClass;                    /*pointer to registered class name */
  25252.  
  25253.  PSZ  pszName;                     /*pointer to window text */
  25254.  
  25255.  ULONG  flStyle;                   /*window style */
  25256.  
  25257.  SHORT  x;                         /*horizontal position of window */
  25258.  
  25259.  SHORT  y;                         /*vertical position of window */
  25260.  
  25261.  SHORT  cx;                        /*window width */
  25262.  
  25263.  SHORT  cy;                        /*window height */
  25264.  
  25265.  HWND  hwndOwner;                  /*owner-window handle */
  25266.  
  25267.  HWND  hwndInsertBehind;           /*handle to sibling window */
  25268.  
  25269.  USHORT  id;                       /*window identifier */
  25270.  
  25271.  PVOID  pCtlData;                  /*pointer to buffer */
  25272.  
  25273.  PVOID  pPresParams;               /*pointer to structure with pres. params.
  25274.                                    */
  25275.  
  25276.  
  25277.  The WinCreateWindow function creates a new window.
  25278.  
  25279.  
  25280.  Parameters
  25281.  
  25282.  hwndParent  Specifies the parent window of the new window. Any valid window
  25283.  handle can be used.
  25284.  
  25285.  pszClass  Points to the registered class name. This parameter can be an
  25286.  application-specified name (defined by the WinRegisterClass function), the
  25287.  name of a preregistered window class, or a window-class (WC) constant.
  25288.  
  25289.  pszName  Points to window text or other class-specific data. The actual
  25290.  structure of the data is class-specific. This data is usually a
  25291.  null-terminated string and is often displayed in the window.
  25292.  
  25293.  flStyle  Specifies the window style. It can be a combination of one or more
  25294.  of the following values:
  25295.  
  25296.  Value                             Meaning
  25297.  ────────────────────────────────────────────────────────────────────────────
  25298.  
  25299.  WS_CLIPCHILDREN                   Prevents a window from painting over its
  25300.                                    child windows.
  25301.  
  25302.  WS_CLIPSIBLINGS                   Prevents a window from painting over its
  25303.                                    sibling windows. ,
  25304.  
  25305.  WS_DISABLED                       Disables mouse and keyboard input to the
  25306.                                    window. It is used to temporarily
  25307.                                    prevent the user from using the window.
  25308.  
  25309.  WS_MAXIMIZED                      Enlarges the window to the maximum size.
  25310.  
  25311.  WS_MINIMIZED                      Reduces the window to the minimum size.
  25312.  
  25313.  WS_PARENTCLIP                     Prevents a window from painting over its
  25314.                                    parent window.
  25315.  
  25316.  WS_SAVEBITS                       Saves the image under the window as a
  25317.                                    bitmap. When the window is moved or
  25318.                                    hidden, the system restores the image by
  25319.                                    copying the bits.
  25320.  
  25321.  WS_SYNCPAINT                      Causes the window to immediately receive
  25322.                                    WM_PAINT messages after a part of the
  25323.                                    window becomes invalid. Unless this
  25324.                                    style is set, the window receives
  25325.                                    WM_PAINT messages only when no other
  25326.                                    message is waiting to be processed.
  25327.  
  25328.  WS_VISIBLE                        Makes the window visible. This window is
  25329.                                    drawn on the screen unless overlapping
  25330.                                    windows completely obscure it. Windows
  25331.                                    without this style are hidden.
  25332.  
  25333.  
  25334.  
  25335.  x  Specifies the horizontal position of the window, relative to the origin
  25336.  of the parent window.
  25337.  
  25338.  y  Specifies the vertical position of the window, relative to the origin of
  25339.  the parent window.
  25340.  
  25341.  cx  Specifies the window width, in pels.
  25342.  
  25343.  cy  Specifies the window height, in pels.
  25344.  
  25345.  hwndOwner  Identifies the owner window.
  25346.  
  25347.  hwndInsertBehind  Identifies the sibling window behind which the specified
  25348.  window is placed. If this parameter is HWND_TOP, the specified window is
  25349.  placed on top of all its sibling windows. If this parameter is HWND_BOTTOM,
  25350.  the specified window is placed behind all its sibling windows. If the
  25351.  hwndInsertBehind parameter is neither HWND_TOP nor HWND_BOTTOM, or it is not
  25352.  a child window of the window identified by hwndParent, NULL is returned.
  25353.  
  25354.  id  Specifies the window identifier (a value given by the application that
  25355.  allows a specific child window to be identified). For example, the controls
  25356.  of a dialog box have unique identifiers so that an owner window can
  25357.  distinguish which control has notified it. Window identifiers are also used
  25358.  for frame windows.
  25359.  
  25360.  pCtlData  Points to the buffer that contains class-specific information.
  25361.  This data is passed to the window procedure by the WM_CREATE message.
  25362.  
  25363.  pPresParams  Points to a PRESPARAMS structure that contains presentation
  25364.  parameters for the window. This parameter is NULL if there are no
  25365.  presentation parameters. The PRESPARAMS structure has the following form:
  25366.  
  25367.  typedef struct _PRESPARAMS {
  25368.      ULONG cb;
  25369.      PARAM   aparam[1];
  25370.  } PRESPARAMS;
  25371.  
  25372.  
  25373.  
  25374.  
  25375.  For a full description, see Chapter 4, "Types, Macros, Structures."
  25376.  
  25377.  
  25378.  Return Value
  25379.  
  25380.  The return value is the handle of the window if the function is successful
  25381.  or NULL if an error occurs.
  25382.  
  25383.  
  25384.  Comments
  25385.  
  25386.  The WinCreateWindow function sends a WM_CREATE message to the window
  25387.  procedure of the window being created, and then sends the WM_ADJUSTWINDOWPOS
  25388.  message before the window is displayed. The values passed are those given to
  25389.  the WinCreateWindow function.
  25390.  
  25391.  The WM_SIZE message is not sent by WinCreateWindow while the window is being
  25392.  created. Any required size processing is performed during the processing of
  25393.  the WM_CREATE message.
  25394.  
  25395.  
  25396.  See Also
  25397.  
  25398.  WinCreateStdWindow, WinQueryObjectWindow, WinRegisterClass
  25399.  
  25400.  
  25401.  Changes
  25402.  
  25403.  The pPresParams parameter now points to a PRESPARAMS structure.
  25404.  
  25405.  
  25406.  █    WinDefAVioWindowProc
  25407.  ────────────────────────────────────────────────────────────────────────────
  25408.  
  25409.  MRESULT WinDefAVioWindowProc  (hwnd, msg, mp1, mp2)
  25410.  
  25411.  HWND  hwnd;                       /*handle of the window */
  25412.  
  25413.  USHORT  msg;                      /*message */
  25414.  
  25415.  MPARAM  mp1;                      /*message parameter */
  25416.  
  25417.  MPARAM  mp2;                      /*message parameter */
  25418.  
  25419.  
  25420.  The WinDefAVioWindowProc function processes WM_SIZE messages for an
  25421.  advanced-video-input-and-output (AVIO) window. An AVIO application must use
  25422.  this function instead of the WinDefWindowProc function to process any
  25423.  WM_SIZE message.
  25424.  
  25425.  
  25426.  Parameters
  25427.  
  25428.  hwnd  Identifies the window that received the message.
  25429.  
  25430.  msg  Specifies the message.
  25431.  
  25432.  mp1  Specifies message parameter 1.
  25433.  
  25434.  mp2  Specifies message parameter 2.
  25435.  
  25436.  
  25437.  Return Value
  25438.  
  25439.  The return value is zero if the function is successful.
  25440.  
  25441.  
  25442.  See Also
  25443.  
  25444.  WinDefWindowProc, WM_SIZE
  25445.  
  25446.  
  25447.  Corrections
  25448.  
  25449.  The WinDefAVioWindowProc function is used only to process the WM_SIZE
  25450.  message. It cannot be used in place of the WinDefWindowProc function to call
  25451.  the default window procedure.
  25452.  
  25453.  
  25454.  █    WinDeleteLibrary
  25455.  ────────────────────────────────────────────────────────────────────────────
  25456.  
  25457.  BOOL WinDeleteLibrary  (hab, hlib)
  25458.  
  25459.  HAB  hab;                         /*anchor-block handle */
  25460.  
  25461.  HLIB  hlib;                       /*handle of library to be deleted */
  25462.  
  25463.  
  25464.  The WinDeleteLibrary function deletes a library previously loaded by the
  25465.  WinLoadLibrary function.
  25466.  
  25467.  
  25468.  Parameters
  25469.  
  25470.  hab  Identifies the anchor block.
  25471.  
  25472.  hlib  Identifies the library to be deleted. This handle must have been
  25473.  created by the WinLoadLibrary function.
  25474.  
  25475.  
  25476.  Return Value
  25477.  
  25478.  The return value is TRUE if the function is successful or FALSE if an error
  25479.  occurs.
  25480.  
  25481.  
  25482.  See Also
  25483.  
  25484.  WinLoadLibrary
  25485.  
  25486.  
  25487.  █    WinDeleteProcedure
  25488.  ────────────────────────────────────────────────────────────────────────────
  25489.  
  25490.  BOOL WinDeleteProcedure  (hab, pfnwpProc)
  25491.  
  25492.  HAB  hab;                         /*anchor-block handle */
  25493.  
  25494.  PFNWP  pfnwpProc;                 /*pointer to window function */
  25495.  
  25496.  
  25497.  The WinDeleteProcedure function deletes a procedure that was previously
  25498.  loaded using the WinLoadProcedure function.
  25499.  
  25500.  
  25501.  Parameters
  25502.  
  25503.  hab  Identifies the anchor block.
  25504.  
  25505.  pfnwpProc  Points to the procedure to be deleted. This procedure must have
  25506.  been previously loaded by the WinLoadProcedure function.
  25507.  
  25508.  
  25509.  Return Value
  25510.  
  25511.  The return value is TRUE if the function is successful or FALSE if an error
  25512.  occurs.
  25513.  
  25514.  
  25515.  See Also
  25516.  
  25517.  WinDeleteLibrary, WinLoadProcedure
  25518.  
  25519.  
  25520.  █    WinDestroyHelpInstance
  25521.  ────────────────────────────────────────────────────────────────────────────
  25522.  
  25523.  BOOL WinDestroyHelpInstance  (hwndHelpInstance)
  25524.  
  25525.  HWND  hwndHelpInstance;           /*handle of instance to destroy */
  25526.  
  25527.  
  25528.  The WinDestroyHelpInstance function destroys a help instance.
  25529.  
  25530.  
  25531.  Parameters
  25532.  
  25533.  hwndHelpInstance  Identifies the help instance to destroy. This handle must
  25534.  have been previously created by using the WinCreateHelpInstance function.
  25535.  
  25536.  
  25537.  Return Value
  25538.  
  25539.  The return value is TRUE if the help instance is successfully destroyed or
  25540.  FALSE if an error occurs.
  25541.  
  25542.  
  25543.  See Also
  25544.  
  25545.  WinCreateHelpInstance
  25546.  
  25547.  
  25548.  █    WinDismissDlg
  25549.  ────────────────────────────────────────────────────────────────────────────
  25550.  
  25551.  BOOL WinDismissDlg  (hwndDlg, usResult)
  25552.  
  25553.  HWND  hwndDlg;                    /*handle of the dialog window */
  25554.  
  25555.  USHORT  usResult;                 /*result code to return */
  25556.  
  25557.  
  25558.  The WinDismissDlg function hides the dialog window and causes the
  25559.  WinProcessDlg or WinDlgBox function to return.
  25560.  
  25561.  
  25562.  Parameters
  25563.  
  25564.  hwndDlg  Identifies the dialog window to be hidden.
  25565.  
  25566.  usResult  Specifies the value that is returned to the caller of
  25567.  WinProcessDlg or WinDlgBox.
  25568.  
  25569.  
  25570.  Return Value
  25571.  
  25572.  The return value is TRUE if the function is successful or FALSE if an error
  25573.  occurs.
  25574.  
  25575.  
  25576.  Comments
  25577.  
  25578.  This function is required to complete the processing of a modal dialog
  25579.  window and is called from its dialog procedure.
  25580.  
  25581.  The WinDismissDlg function is automatically called by the WinDefDlgProc
  25582.  function upon receiving a WM_COMMAND message. The WinDefDlgProc function
  25583.  will set usResult to the identifier of the control that generated the
  25584.  WM_COMMAND message.
  25585.  
  25586.  Note that this function can be called from a modeless dialog box, although
  25587.  this is not necessary since there is no internal message-processing loop. If
  25588.  the function is called, the dialog box window is hidden. The application
  25589.  must destroy the dialog box window, if required.
  25590.  
  25591.  
  25592.  Example
  25593.  
  25594.  This example shows a typical dialog procedure that has both an OK and a
  25595.  Cancel button. If the user selects the OK button, WinDismissDlg is called
  25596.  with a result value of TRUE. If the user selects the Cancel button,
  25597.  WinDismissDlg is called with a result value of FALSE.
  25598.  
  25599.  case WM_COMMAND:
  25600.      switch (SHORT1FROMMP(mp1)) {
  25601.          case ID_ENTER:    /* OK button selected  */
  25602.              WinDismissDlg(hwnd, TRUE);
  25603.              return (0L);
  25604.  
  25605.          case ID_CANCEL:   /* Cancel button selected */
  25606.              WinDismissDlg(hwnd, FALSE);
  25607.              return (0L);
  25608.  
  25609.  
  25610.  
  25611.  
  25612.  
  25613.  See Also
  25614.  
  25615.  WinDlgBox, WinProcessDlg
  25616.  
  25617.  
  25618.  Corrections
  25619.  
  25620.  In the example, if the user selects the Cancel button, WinDismissDlg is
  25621.  called with a result value of FALSE, not TRUE as previous documented.
  25622.  
  25623.  
  25624.  █    WinDrawBitmap
  25625.  ────────────────────────────────────────────────────────────────────────────
  25626.  
  25627.  BOOL WinDrawBitmap  (hpsDst, hbm, prclSrc, pptlDst, clrFore, clrBack, fs)
  25628.  
  25629.  HPS  hpsDst;                      /*handle of the destination presentation
  25630.                                    space */
  25631.  
  25632.  HBITMAP  hbm;                     /*handle of the bitmap */
  25633.  
  25634.  PRECTL  prclSrc;                  /*address of structure with rectangle
  25635.                                    coordinates */
  25636.  
  25637.  PPOINTL  pptlDst;                 /*address of structure with bitmap
  25638.                                    position */,
  25639.  
  25640.  LONG  clrFore;                    /*color of the foreground */
  25641.  
  25642.  LONG  clrBack;                    /*color of the background */
  25643.  
  25644.  USHORT  fs;                       /*bitmap-drawing flags */
  25645.  
  25646.  
  25647.  The WinDrawBitmap function draws a bitmap using the current image colors and
  25648.  mixes.
  25649.  
  25650.  
  25651.  Parameters
  25652.  
  25653.  hpsDst  Identifies the presentation space in which the bitmap is drawn.
  25654.  
  25655.  hbm  Identifies the bitmap.
  25656.  
  25657.  prclSrc  Points to the RECTL data structure that contains the coordinates of
  25658.  the rectangle to be drawn. If this parameter is NULL, the entire bitmap is
  25659.  drawn. The RECTL structure has the following form:
  25660.  
  25661.  typedef struct _RECTL {
  25662.      LONG  xLeft;
  25663.      LONG  yBottom;
  25664.      LONG  xRight;
  25665.      LONG  yTop;
  25666.  } RECTL;
  25667.  
  25668.  
  25669.  
  25670.  
  25671.  For a full description, see Chapter 4, "Types, Macros, Structures."
  25672.  
  25673.  pptlDst  Points to the position of the lower left of the bitmap in the
  25674.  presentation space (in device coordinates).
  25675.  
  25676.  clrFore  Specifies the color of the foreground.
  25677.  
  25678.  clrBack  Specifies the color of the background.
  25679.  
  25680.  fs  Specifies the flags that determine how the bitmap is drawn. It can be
  25681.  one of the following values:
  25682.  
  25683.  Value                             Meaning
  25684.  ────────────────────────────────────────────────────────────────────────────
  25685.  
  25686.  DBM_HALFTONE                      Use the OR operator to combine the
  25687.                                    bitmap with an alternating pattern of
  25688.                                    ones and zeros before drawing it. This
  25689.                                    flag can be used in conjunction with
  25690.                                    either DBM_NORMAL or DBM_INVERT.
  25691.  
  25692.  DBM_IMAGEATTRS                    The clrFore and clrBack parameters are
  25693.                                    ignored and the image attribute colors
  25694.                                    already selected in hpsDst are used
  25695.                                    instead.
  25696.  
  25697.  DBM_INVERT                        Draw the bitmap inverted, using
  25698.                                    ROP_NOTSRCCOPY.
  25699.  
  25700.  DBM_NORMAL                        Draw the bitmap normally, using
  25701.                                    ROP_SRCCOPY.
  25702.  
  25703.  DBM_STRETCH                       The pptlDst parameter points to a RECTL
  25704.                                    data structure, representing a rectangle
  25705.                                    in the destination presentation space to
  25706.                                    which the bitmap should be stretched.
  25707.  
  25708.  
  25709.  
  25710.  Return Value
  25711.  
  25712.  The return value is TRUE if the function is successful or FALSE if an error
  25713.  occurs.
  25714.  
  25715.  
  25716.  See Also
  25717.  
  25718.  GpiCreateBitmap, GpiLoadBitmap, WinGetSysBitmap
  25719.  
  25720.  
  25721.  Corrections
  25722.  
  25723.  Previous documentation incorrectly stated that the pptlDst parameter was
  25724.  specified in presentation-space coordinates. This parameter is specified in
  25725.  device coordinates.
  25726.  
  25727.  
  25728.  █    WinEnumDlgItem
  25729.  ────────────────────────────────────────────────────────────────────────────
  25730.  
  25731.  HWND WinEnumDlgItem  (hwndDlg, hwnd, code, fLock)
  25732.  
  25733.  HWND  hwndDlg;                    /*handle of the dialog window */
  25734.  
  25735.  HWND  hwnd;                       /*handle of the child window */
  25736.  
  25737.  USHORT  code;                     /*dialog item to return */
  25738.  
  25739.  BOOL  fLock;                      /*lock/unlock flag */
  25740.  
  25741.  
  25742.  The WinEnumDlgItem function returns the handle of a dialog item within a
  25743.  dialog window.
  25744.  
  25745.  
  25746.  Parameters
  25747.  
  25748.  hwndDlg  Identifies the dialog window that contains the dialog item.
  25749.  
  25750.  hwnd  Identifies the child window of the dialog window. This may be an
  25751.  immediate child window or a window lower in the hierarchy, such as a child
  25752.  of a child window.
  25753.  
  25754.  code  Specifies which dialog item to return. This parameter is one of the
  25755.  following values:
  25756.  
  25757.  Value                             Meaning
  25758.  ────────────────────────────────────────────────────────────────────────────
  25759.  
  25760.  EDI_FIRSTGROUPITEM                First item in same group.
  25761.  
  25762.  EDI_FIRSTTABITEM                  First item in dialog window with style
  25763.                                    WS_TABSTOP. The hwnd window is ignored.
  25764.  
  25765.  EDI_LASTGROUPITEM                 Last item in same group.
  25766.  
  25767.  EDI_LASTTABITEM                   Last item in dialog box with style
  25768.                                    WS_TABSTOP. The hwnd window is ignored.
  25769.  
  25770.  EDI_NEXTGROUPITEM                 Next item in same group. Wraps to
  25771.                                    beginning of group when end of group is
  25772.                                    reached.
  25773.  
  25774.  EDI_NEXTTABITEM                   Next item with style WS_TABSTOP. Wraps
  25775.                                    around to beginning of dialog-item list
  25776.                                    when end is reached.
  25777.  
  25778.  EDI_PREVGROUPITEM                 Previous item in same group. Wraps to
  25779.                                    end of group when start of group is
  25780.                                    reached.
  25781.  
  25782.  EDI_PREVTABITEM                   Previous item with style WS_TABSTOP.
  25783.                                    Wraps to end of dialog-item list when
  25784.                                    beginning is reached.
  25785.  
  25786.  
  25787.  
  25788.  fLock  This parameter is ignored by MS OS/2 versions 1.2 and later.
  25789.  
  25790.  
  25791.  Return Value
  25792.  
  25793.  The return value is the item handle obtained by this function, specified by
  25794.  the code parameter. The window is always an immediate child window of the
  25795.  window identified by the hwndDlg parameter.
  25796.  
  25797.  
  25798.  See Also
  25799.  
  25800.  WinBeginEnumWindows, WinLockWindow
  25801.  
  25802.  
  25803.  Changes
  25804.  
  25805.  The fLock parameter is ignored in MS OS/2 versions 1.2 and later.
  25806.  
  25807.  
  25808.  █    WinGetDlgMsg
  25809.  ────────────────────────────────────────────────────────────────────────────
  25810.  
  25811.  BOOL WinGetDlgMsg  (hwnd, pqmsg)
  25812.  
  25813.  HWND  hwnd;                       /*dialog-window handle */
  25814.  
  25815.  PQMSG  pqmsg;                     /*pointer to structure with message */
  25816.  
  25817.  
  25818.  The WinGetDlgMsg function retrieves a message intended for a dialog box.
  25819.  This function is used by an application written in a language (for example,
  25820.  COBOL, or FORTRAN) that does not allow the system to call the application's
  25821.  window procedure (this is called a non-reentrant window procedure).
  25822.  
  25823.  
  25824.  Parameters
  25825.  
  25826.  hwnd  Identifies the dialog window.
  25827.  
  25828.  pqmsg  Points to the QMSG structure that contains a message. The QMSG
  25829.  structure has the following form:
  25830.  
  25831.  typedef struct _QMSG {
  25832.      HWND hwnd;
  25833.      USHORT msg;
  25834.      MPARAM mp1;
  25835.      MPARAM mp2;
  25836.      ULONG time;
  25837.      POINTL ptl;
  25838.  } QMSG;
  25839.  
  25840.  
  25841.  
  25842.  
  25843.  For a full description, see Chapter 4, "Types, Macros, Structures."
  25844.  
  25845.  
  25846.  Return Value
  25847.  
  25848.  The return value is TRUE if there is a message for the dialog box, or it is
  25849.  FALSE if the dialog is complete or an error occurs.
  25850.  
  25851.  
  25852.  Comments
  25853.  
  25854.  The WinGetDlgMsg function allows a language that cannot support window
  25855.  procedures to provide the function of a modal dialog window. The application
  25856.  creates a modeless box dialog by using the WinCreateDlg or WinLoadDlg
  25857.  functions and then calls WinGetDlgMsg to process messages associated with
  25858.  the dialog box. The application should call this function in a loop until it
  25859.  receives a WM_QUIT message. The application should call WinDefDlgProc for
  25860.  the messages it does not want rather than dispatching the messages it
  25861.  receives.
  25862.  
  25863.  To create a window that uses a non-reentrant window procedure, use NULL for
  25864.  the pfnWndProc parameter of the WinRegisterClass function.
  25865.  
  25866.  The first time this function is called, the owner of the window specified by
  25867.  hwnd is disabled, thereby preventing input into windows other than the
  25868.  dialog box. The owner of the window specified by hwnd is enabled when the
  25869.  WinDismissDlg function is issued by the application or by the default dialog
  25870.  procedure.
  25871.  
  25872.  Synchronous messages that would normally go directly to the window procedure
  25873.  will be converted to one of the following messages and retrieved by the
  25874.  WinGetDlgMsg function:
  25875.  
  25876.       WM_PPAINT
  25877.       WM_PSETFOCUS
  25878.       WM_PSYSCOLORCHANGE
  25879.       WM_PSIZE
  25880.       WM_PACTIVATE
  25881.       WM_PCONTROL
  25882.  
  25883.  
  25884.  
  25885.  
  25886.  
  25887.  See Also
  25888.  
  25889.  WinCreateDlg, WinDefDlgProc, WinDismissDlg, WinLoadDlg, WinRegisterClass
  25890.  
  25891.  
  25892.  █    WinGetErrorInfo
  25893.  ────────────────────────────────────────────────────────────────────────────
  25894.  
  25895.  PERRINFO WinGetErrorInfo  (hab)
  25896.  
  25897.  HAB  hab;                         /*handle of the anchor block */
  25898.  
  25899.  
  25900.  The WinGetErrorInfo function returns detailed error information.
  25901.  
  25902.  
  25903.  Parameters
  25904.  
  25905.  hab  Identifies the anchor block.
  25906.  
  25907.  
  25908.  Return Value
  25909.  
  25910.  The return value points to an ERRINFO structure that contains information
  25911.  about the previous error code for the current thread; or it is NULL if no
  25912.  error information is available.
  25913.  
  25914.  
  25915.  Comments
  25916.  
  25917.  This function allocates a single private segment to contain the ERRINFO
  25918.  structure. All pointers to string fields within ERRINFO are offsets to
  25919.  memory within that segment.
  25920.  
  25921.  The ERRINFO structure has the following form:
  25922.  
  25923.  typedef struct _ERRINFO {    /* erri */
  25924.      USHORT    cbFixedErrInfo;
  25925.      ERRORID   idError;
  25926.      USHORT    cDetailLevel;
  25927.      USHORT    offaoffszMsg;
  25928.      USHORT    offBinaryData;
  25929.  } ERRINFO;
  25930.  
  25931.  
  25932.  For a full description, see Chapter 4, "Types, Macros, Structures."
  25933.  
  25934.  The memory allocated by this function is not freed until the returned
  25935.  pointer is passed to the WinFreeErrorInfo function.
  25936.  
  25937.  WinGetErrorInfo does not release saved error information. Consecutive calls
  25938.  to this function return the same information.
  25939.  
  25940.  
  25941.  See Also
  25942.  
  25943.  WinFreeErrorInfo, WinGetLastError
  25944.  
  25945.  
  25946.  Corrections
  25947.  
  25948.  WinGetErrorInfo does not release saved error information. Consecutive calls
  25949.  to this function return the same information.
  25950.  
  25951.  
  25952.  █    WinGetNextWindow
  25953.  ────────────────────────────────────────────────────────────────────────────
  25954.  
  25955.  HWND WinGetNextWindow  (henum)
  25956.  
  25957.  HENUM  henum;                     /*handle of the enumeration list */
  25958.  
  25959.  
  25960.  The WinGetNextWindow function obtains the handle of the next window in a
  25961.  specified enumeration list.
  25962.  
  25963.  The enumeration list details the window hierarchy at the time
  25964.  WinBeginEnumWindows was called. Enumeration starts with the top-most child
  25965.  window (listed first) and proceeds through the list each time the function
  25966.  is called, until all windows have been enumerated. Once all windows have
  25967.  been enumerated, the function returns NULL. The enumeration then returns to
  25968.  the top of the list and the handle of the top-most child window is returned
  25969.  on the next call.
  25970.  
  25971.  
  25972.  Parameters
  25973.  
  25974.  henum  Identifies the enumeration list. This parameter is created by the
  25975.  WinBeginEnumWindows function.
  25976.  
  25977.  
  25978.  Return Value
  25979.  
  25980.  The return value is the handle of the next window in the enumeration list,
  25981.  or it is NULL if an error occurs.
  25982.  
  25983.  
  25984.  See Also
  25985.  
  25986.  WinBeginEnumWindows, WinLockWindow
  25987.  
  25988.  
  25989.  Changes
  25990.  
  25991.  This function no longer locks the window.
  25992.  
  25993.  
  25994.  █    WinGetSysBitmap
  25995.  ────────────────────────────────────────────────────────────────────────────
  25996.  
  25997.  HBITMAP WinGetSysBitmap  (hwndDesktop, ibm)
  25998.  
  25999.  HWND  hwndDesktop;                /*handle of the desktop */
  26000.  
  26001.  USHORT  ibm;                      /*index of the system bitmap */
  26002.  
  26003.  
  26004.  The WinGetSysBitmap function returns a handle to one of the standard bitmaps
  26005.  provided by the system. This bitmap can be used for any of the normal bitmap
  26006.  operations. When your application is done with the bitmap, it should free it
  26007.  by calling GpiDeleteBitmap.
  26008.  
  26009.  
  26010.  Parameters
  26011.  
  26012.  hwndDesktop  Identifies the desktop window. This parameter can be
  26013.  HWND_DESKTOP or the desktop window handle.
  26014.  
  26015.  ibm  Specifies the system-bitmap index value. It can be one of the following
  26016.  values:
  26017.  
  26018.  Bitmap                            Description
  26019.  ────────────────────────────────────────────────────────────────────────────
  26020.  
  26021.  SBMP_BTNCORNERS                   Push button corners.
  26022.  
  26023.  SBMP_CHECKBOXES                   Check box/radio button check mark.
  26024.  
  26025.  SBMP_CHILDSYSMENU                 Smaller version of the system menu
  26026.                                    bitmap to use in child windows.
  26027.  
  26028.  SBMP_COMBODOWN                    Combination-box down arrow.
  26029.  
  26030.  SBMP_DRIVE                        A symbol used by the file system to
  26031.                                    indicate a disk drive.
  26032.  
  26033.  SBMP_FILE                         A symbol used by the file system to
  26034.                                    indicate a file.
  26035.  
  26036.  SBMP_FOLDER                       A symbol used by the file system to show
  26037.                                    subdirectories.
  26038.  
  26039.  SBMP_MAXBUTTON                    Maximize button.
  26040.  
  26041.  SBMP_MENUATTACHED                 A symbol used to indicate that a menu
  26042.                                    item has an attached hierarchical menu.
  26043.  
  26044.  SBMP_MENUCHECK                    Menu check mark.
  26045.  
  26046.  SBMP_MINBUTTON                    Minimize button.
  26047.  
  26048.  SBMP_PROGRAM                      A symbol used by the file system to
  26049.                                    indicate that a file is an executable
  26050.                                    program.
  26051.  
  26052.  SBMP_RESTOREBUTTON                Restore button.
  26053.  
  26054.  SBMP_SBDNARROW                    Scroll-bar down arrow.
  26055.  
  26056.  SBMP_SBDNARROWDEP                 Scroll-bar down arrow is pressed.
  26057.  
  26058.  SBMP_SBDNARROWDIS                 Scroll-bar down arrow is disabled.
  26059.  
  26060.  SBMP_SBLFARROW                    Scroll-bar left arrow.
  26061.  
  26062.  SBMP_SBLFARROWDEP                 Scroll-bar left arrow is pressed.
  26063.  
  26064.  SBMP_SBLFARROWDIS                 Scroll-bar left arrow is disabled.
  26065.  
  26066.  SBMP_SBRGARROW                    Scroll-bar right arrow.
  26067.  
  26068.  SBMP_SBRGARROWDEP                 Scroll-bar right arrow is pressed.
  26069.  
  26070.  SBMP_SBRGARROWDIS                 Scroll-bar right arrow is disabled.
  26071.  
  26072.  SBMP_SBUPARROW                    Scroll-bar up arrow.
  26073.  
  26074.  SBMP_SBUPARROWDEP                 Scroll-bar up arrow is pressed.
  26075.  
  26076.  SBMP_SBUPARROWDIS                 Scroll-bar up arrow is disabled.
  26077.  
  26078.  SBMP_SIZEBOX                      A symbol used to indicate an area of a
  26079.                                    window that a user can click to resize
  26080.                                    the window.
  26081.  
  26082.  SBMP_SYSMENU                      System menu.
  26083.  
  26084.  SBMP_TREEMINUS                    A symbol used by the file system to show
  26085.                                    that an entry in the directory tree
  26086.                                    contains no more files.
  26087.  
  26088.  SBMP_TREEPLUS                     A symbol used by the file system to show
  26089.                                    that an entry in the directory tree
  26090.                                    contains more files.
  26091.  
  26092.  
  26093.  
  26094.  Return Value
  26095.  
  26096.  The return value is a handle to a bitmap, or it is NULL if an error occurs.
  26097.  
  26098.  
  26099.  See Also
  26100.  
  26101.  GpiDeleteBitmap, WinDrawBitmap
  26102.  
  26103.  
  26104.  Changes
  26105.  
  26106.  The following system bitmaps have been added:
  26107.  
  26108.  Value                             Meaning
  26109.  ────────────────────────────────────────────────────────────────────────────
  26110.  
  26111.  SBMP_SBUPARROWDEP                 Scroll-bar up arrow is pressed.
  26112.  
  26113.  SBMP_SBDNARROWDEP                 Scroll-bar down arrow is pressed.
  26114.  
  26115.  SBMP_SBLFARROWDEP                 Scroll-bar left arrow is pressed.
  26116.  
  26117.  SBMP_SBRGARROWDEP                 Scroll-bar right arrow is pressed.
  26118.  
  26119.  SBMP_SBUPARROWDIS                 Scroll-bar up arrow is disabled.
  26120.  
  26121.  SBMP_SBDNARROWDIS                 Scroll-bar down arrow is disabled.
  26122.  
  26123.  SBMP_SBLFARROWDIS                 Scroll-bar left arrow is disabled.
  26124.  
  26125.  SBMP_SBRGARROWDIS                 Scroll-bar right arrow is disabled.
  26126.  
  26127.  SBMP_COMBODOWN                    Combination-box down arrow.
  26128.  
  26129.  
  26130.  
  26131.  █    WinInstStartApp
  26132.  ────────────────────────────────────────────────────────────────────────────
  26133.  
  26134.  HAPP WinInstStartApp  (hini, hwndNotifyWindow, cNames, paszNames,
  26135.  pszCmdLine, pData, fsOption)
  26136.  
  26137.  HINI  hini;                       /*initialization-file handle */
  26138.  
  26139.  HWND  hwndNotifyWindow;           /*notification-window handle */
  26140.  
  26141.  USHORT  cNames;                   /*count of elements in the application
  26142.                                    array */
  26143.  
  26144.  PSZ *  paszNames;                 /*identifier of application */
  26145.  
  26146.  PSZ  pszCmdLine;                  /*input parameters for application */
  26147.  
  26148.  PVOID  pData;                     /*must be zero */
  26149.  
  26150.  USHORT  fsOptions;                /*option flags */
  26151.  
  26152.  
  26153.  The WinInstStartApp function starts an installed application.
  26154.  
  26155.  
  26156.  Parameters
  26157.  
  26158.  hini  Specifies the handle of the initialization file where the application
  26159.  is found.
  26160.  
  26161.  hwndNotifyWindow  Identifies the window to which a notification message
  26162.  should be sent. If this parameter is NULL, no notification message is sent.
  26163.  
  26164.  cNames  Specifies the number of elements in the array pointed to by the
  26165.  paszNames parameter. This value must be 1 or 2.
  26166.  
  26167.  paszNames  Points to an array of pointers which, in turn, point to strings
  26168.  that contain the name of the application and group (if any) where the
  26169.  application is found. The first element of the array points to the
  26170.  application name, the second to the group name.
  26171.  
  26172.  pszCmdLine  Points to the string that contains the command line to be passed
  26173.  to the application.
  26174.  
  26175.  pData  Reserved value; must be zero.
  26176.  
  26177.  fsOptions  Specifies the options to be used to start the application. This
  26178.  parameter can be one of the following values:
  26179.  
  26180.  Value                             Meaning
  26181.  ────────────────────────────────────────────────────────────────────────────
  26182.  
  26183.  SAF_INSTALLEDCMDLINE              The command-line parameters in the Task
  26184.                                    List are used. Any parameters specified
  26185.                                    by pszCmdLine are ignored.
  26186.  
  26187.  SAF_STARTCHILDAPP                 The application is started as a child
  26188.                                    session of the session from which the
  26189.                                    WinInstStartApp function is called.
  26190.  
  26191.  
  26192.  
  26193.  Return Value
  26194.  
  26195.  The return value is a handle to the application started if the function is
  26196.  successful or NULL if an error occurs.
  26197.  
  26198.  
  26199.  Errors
  26200.  
  26201.  Possible errors may be retrieved with the WinGetLastError function, and may
  26202.  be one of the following:
  26203.  
  26204.       PMERR_INVALID_PARAMETERS
  26205.       PMERR_INVALID_APPL
  26206.       PMERR_INVALID_WINDOW
  26207.       PMERR_CANNOT_START
  26208.       PMERR_STARTED_IN_BACKGROUND
  26209.       PMERR_DOS_ERROR
  26210.       PMERR_NOT_ENOUGH_MEM
  26211.  
  26212.  
  26213.  
  26214.  
  26215.  
  26216.  See Also
  26217.  
  26218.  WinTerminateApp
  26219.  
  26220.  
  26221.  █    WinIsWindowShowing
  26222.  ────────────────────────────────────────────────────────────────────────────
  26223.  
  26224.  BOOL WinIsWindowShowing  (hwnd)
  26225.  
  26226.  HWND  hwnd;                       /*window handle */
  26227.  
  26228.  
  26229.  The WinIsWindowShowing function determines if all or part of a window is
  26230.  currently displayed on the screen. This is in contrast to the
  26231.  WinIsWindowVisible function, which returns the actual visibility state of
  26232.  the window rather than its displayed state.
  26233.  
  26234.  
  26235.  Parameters
  26236.  
  26237.  hwnd  Identifies the window to be checked.
  26238.  
  26239.  
  26240.  Return Value
  26241.  
  26242.  The return value is TRUE if any part of the identified window is visible, it
  26243.  is FALSE if no part of the window is visible.
  26244.  
  26245.  
  26246.  Comments
  26247.  
  26248.  The WinIsWindowShowing function also returns FALSE if it is called while the
  26249.  user is moving a window.
  26250.  
  26251.  
  26252.  See Also
  26253.  
  26254.  WinIsWindowEnabled, WinIsWindowVisible
  26255.  
  26256.  
  26257.  █    WinLoadHelpTable
  26258.  ────────────────────────────────────────────────────────────────────────────
  26259.  
  26260.  BOOL WinLoadHelpTable  (hwndHelpInstance, idHelpTable, hmodModule)
  26261.  
  26262.  HWND  hwndHelpInstance;           /*handle of help instance */
  26263.  
  26264.  USHORT  idHelpTable;              /*resource ID for help table */
  26265.  
  26266.  HMODULE  hmodModule;              /*resource-module handle */
  26267.  
  26268.  
  26269.  The WinLoadHelpTable function specifies a help table for the given help
  26270.  instance.
  26271.  
  26272.  
  26273.  Parameters
  26274.  
  26275.  hwndHelpInstance  Identifies the help instance. The instance must have been
  26276.  previously created using the WinCreateHelpInstance function.
  26277.  
  26278.  idHelpTable  Specifies the resource ID of the help table.
  26279.  
  26280.  hmodModule  Identifies the module that contains the help table resource.
  26281.  
  26282.  
  26283.  Return Value
  26284.  
  26285.  
  26286.  
  26287.  The return value is TRUE if the function is successful or FALSE if an error
  26288.  occurs.
  26289.  
  26290.  
  26291.  Errors
  26292.  
  26293.  Use the WinGetLastError function to retrieve the error value, which may be
  26294.  the following:
  26295.  
  26296.       HMERR_HELP_INST_CALLED_INVALID
  26297.  
  26298.  
  26299.  
  26300.  
  26301.  
  26302.  Comments
  26303.  
  26304.  Applications can use this function to replace a help instance's initial help
  26305.  table or to set the table if no initial help table is given. The initial
  26306.  help table is specified in the HELPINIT structure when the help instance is
  26307.  created with the WinCreateHelpInstance function. The function replaces the
  26308.  help table without freeing any memory or resources associated with the
  26309.  initial help table.
  26310.  
  26311.  
  26312.  See Also
  26313.  
  26314.  WinCreateHelpInstance
  26315.  
  26316.  
  26317.  █    WinLoadLibrary
  26318.  ────────────────────────────────────────────────────────────────────────────
  26319.  
  26320.  HLIB WinLoadLibrary  (hab, pszModName)
  26321.  
  26322.  HAB  hab;                         /*anchor-block handle */
  26323.  
  26324.  PSZ  pszModName;                  /*pointer to library name */
  26325.  
  26326.  
  26327.  The WinLoadLibrary function loads a dynamic-link module and returns a handle
  26328.  for the module. You can use the module handle to retrieve the entry
  26329.  addresses of procedures in the module.
  26330.  
  26331.  
  26332.  Parameters
  26333.  
  26334.  hab  Identifies the anchor block.
  26335.  
  26336.  pszModName  Points to a null-terminated string; the string must be a valid
  26337.  MS OS/2 filename that specifies the path and filename of the dynamic-link
  26338.  module to be loaded. All dynamic-link modules have the .dll filename
  26339.  extension by default.
  26340.  
  26341.  
  26342.  Return Value
  26343.  
  26344.  The return value is the handle of the library module, or it is NULL if an
  26345.  error occurs.
  26346.  
  26347.  
  26348.  See Also
  26349.  
  26350.  DosLoadModule, WinDeleteLibrary, WinLoadProcedure
  26351.  
  26352.  
  26353.  █    WinLoadProcedure
  26354.  ────────────────────────────────────────────────────────────────────────────
  26355.  
  26356.  PFNWP WinLoadProcedure  (hab, hlib, pszProcName)
  26357.  
  26358.  HAB  hab;                         /*anchor-block handle */
  26359.  
  26360.  HLIB  hlib;                       /*handle of library */
  26361.  
  26362.  PSZ  pszProcName;                 /*pointer to procedure name */
  26363.  
  26364.  
  26365.  The WinLoadProcedure function loads a window procedure from the specified
  26366.  dynamic-link library.
  26367.  
  26368.  
  26369.  Parameters
  26370.  
  26371.  hab  Identifies the anchor block.
  26372.  
  26373.  hlib  Specifies the library handle. If this parameter is NULL, the
  26374.  WinLoadLibrary function will be called, using the value of the pszProcName
  26375.  parameter as the library name.
  26376.  
  26377.  pszProcName  Points to the null-terminated string that specifies the name of
  26378.  the procedure to be loaded.
  26379.  
  26380.  
  26381.  Return Value
  26382.  
  26383.  The return value is a pointer to the window procedure, or it is NULL if an
  26384.  error occurs.
  26385.  
  26386.  
  26387.  See Also
  26388.  
  26389.  WinDeleteProcedure, WinLoadLibrary
  26390.  
  26391.  
  26392.  █    WinLockWindow
  26393.  ────────────────────────────────────────────────────────────────────────────
  26394.  
  26395.  HWND WinLockWindow  (hwnd, fLock)
  26396.  
  26397.  HWND  hwnd;                       /*window  handle */
  26398.  
  26399.  BOOL  fLock;                      /*lock/unlock flag */
  26400.  
  26401.  
  26402.  This function exists for compatibility with MS OS/2 version 1.1. It is not
  26403.  used in MS OS/2 versions 1.2 and later.
  26404.  
  26405.  
  26406.  Changes
  26407.  
  26408.  This function is not used in MS OS/2 versions 1.2 and later.
  26409.  
  26410.  
  26411.  █    WinQueryActiveWindow
  26412.  ────────────────────────────────────────────────────────────────────────────
  26413.  
  26414.  HWND WinQueryActiveWindow  (hwndDesktop, fLock)
  26415.  
  26416.  HWND  hwndDesktop;                /*desktop handle */
  26417.  
  26418.  BOOL  fLock;                      /*lock/unlock flag */
  26419.  
  26420.  
  26421.  The WinQueryActiveWindow function retrieves the active frame window.
  26422.  
  26423.  
  26424.  Parameters
  26425.  
  26426.  hwndDesktop  Identifies the desktop window. This parameter can be
  26427.  HWND_DESKTOP or the desktop window handle.
  26428.  
  26429.  fLock  This parameter is ignored by MS OS/2 versions 1.2 and later.
  26430.  
  26431.  
  26432.  Return Value
  26433.  
  26434.  The return value is the handle of the active window if the function is
  26435.  successful; it is NULL if no window was active at the time of the call or
  26436.  the desktop handle is invalid.
  26437.  
  26438.  
  26439.  Comments
  26440.  
  26441.  If this function is called while the active window is changing, it may
  26442.  return NULL, indicating that no window was active at the time of the call.
  26443.  Because a NULL value can also be returned if the hwndDesktop handle is
  26444.  invalid, the WinGetLastError function must be called to determine if a NULL
  26445.  return value is caused by an invalid hwndDesktop handle or because the
  26446.  active window was changing when WinQueryActiveWindow was called.
  26447.  
  26448.  
  26449.  See Also
  26450.  
  26451.  WinGetLastError, WinLockWindow, WinQueryFocus
  26452.  
  26453.  
  26454.  Changes
  26455.  
  26456.  The fLock parameter is ignored by MS OS/2 versions 1.2 and later.
  26457.  
  26458.  
  26459.  █    WinQueryAnchorBlock
  26460.  ────────────────────────────────────────────────────────────────────────────
  26461.  
  26462.  HAB WinQueryAnchorBlock  (hwnd)
  26463.  
  26464.  HWND  hwnd;                       /*window handle */
  26465.  
  26466.  
  26467.  The WinQueryAnchorBlock function retrieves the handle of the anchor block of
  26468.  a window.
  26469.  
  26470.  
  26471.  Parameters
  26472.  
  26473.  hwnd  Identifies the window whose anchor-block handle is to be returned.
  26474.  
  26475.  
  26476.  Return Value
  26477.  
  26478.  The return value is the anchor-block handle of the specified window if the
  26479.  function is successful or NULL if an error occurs.
  26480.  
  26481.  
  26482.  █    WinQueryCapture
  26483.  ────────────────────────────────────────────────────────────────────────────
  26484.  
  26485.  HWND WinQueryCapture  (hwndDesktop, fLock)
  26486.  
  26487.  HWND  hwndDesktop;                /*desktop handle */
  26488.  
  26489.  BOOL  fLock;                      /*lock/unlock flag */
  26490.  
  26491.  
  26492.  The WinQueryCapture function returns the window handle of the window that
  26493.  has the mouse capture.
  26494.  
  26495.  
  26496.  Parameters
  26497.  
  26498.  hwndDesktop  Identifies the desktop window. This parameter can be
  26499.  HWND_DESKTOP or the desktop-window handle.
  26500.  
  26501.  fLock  This parameter is ignored by MS OS/2 versions 1.2 and later.
  26502.  
  26503.  
  26504.  Return Value
  26505.  
  26506.  The return value is the window handle with the mouse capture if the function
  26507.  is successful; it is NULL if no window has the capture or an error occurs.
  26508.  
  26509.  
  26510.  See Also
  26511.  
  26512.  WinLockWindow, WinSetCapture
  26513.  
  26514.  
  26515.  Changes
  26516.  
  26517.  The fLock parameter is ignored by MS OS/2 versions 1.2 and later.
  26518.  
  26519.  
  26520.  █    WinQueryClipbrdOwner
  26521.  ────────────────────────────────────────────────────────────────────────────
  26522.  
  26523.  HWND WinQueryClipbrdOwner  (hab, fLock)
  26524.  
  26525.  HAB  hab;                         /*anchor-block handle */
  26526.  
  26527.  BOOL  fLock;                      /*lock/unlock viewer flag */
  26528.  
  26529.  
  26530.  The WinQueryClipbrdOwner function retrieves the handle of the window that
  26531.  currently owns the clipboard (if any).
  26532.  
  26533.  
  26534.  Parameters
  26535.  
  26536.  hab  Identifies an anchor block.
  26537.  
  26538.  fLock  This parameter is ignored by MS OS/2 versions 1.2 and later.
  26539.  
  26540.  
  26541.  Return Value
  26542.  
  26543.  The return value is the window handle of the current clipboard owner if the
  26544.  function is successful; it is NULL if the clipboard is not owned by any
  26545.  window or if an error occurs.
  26546.  
  26547.  
  26548.  See Also
  26549.  
  26550.  WinLockWindow, WinQueryClipbrdViewer, WinSetClipbrdOwner
  26551.  
  26552.  
  26553.  Changes
  26554.  
  26555.  The fLock parameter is ignored by MS OS/2 versions 1.2 and later.
  26556.  
  26557.  
  26558.  █    WinQueryClipbrdViewer
  26559.  ────────────────────────────────────────────────────────────────────────────
  26560.  
  26561.  HWND WinQueryClipbrdViewer  (hab, fLock)
  26562.  
  26563.  HAB  hab;                         /*anchor-block handle */
  26564.  
  26565.  BOOL  fLock;                      /*lock/unlock viewer flag */
  26566.  
  26567.  
  26568.  The WinQueryClipbrdViewer function obtains the handle of the current
  26569.  clipboard viewer window (if any).
  26570.  
  26571.  
  26572.  Parameters
  26573.  
  26574.  hab  Identifies the anchor block.
  26575.  
  26576.  fLock  This parameter is ignored by MS OS/2 versions 1.2 and later.
  26577.  
  26578.  
  26579.  Return Value
  26580.  
  26581.  The return value is the handle of the current clipboard viewer window if the
  26582.  function is successful; it is NULL if the clipboard does not have a current
  26583.  viewer window or if an error occurs.
  26584.  
  26585.  
  26586.  See Also
  26587.  
  26588.  WinLockWindow, WinQueryClipbrdOwner, WinSetClipbrdViewer
  26589.  
  26590.  
  26591.  Changes
  26592.  
  26593.  The fLock parameter is ignored by MS OS/2 versions 1.2 and later.
  26594.  
  26595.  
  26596.  █    WinQueryDefinition
  26597.  ────────────────────────────────────────────────────────────────────────────
  26598.  
  26599.  
  26600.  
  26601.  The WinQueryDefinition function provides compatibility with MS OS/2 versions
  26602.  1.1 and earlier. Applications intended exclusively for MS OS/2 versions 1.2
  26603.  and later should use the PrfQueryDefinition function.
  26604.  
  26605.  
  26606.  
  26607.  
  26608.  █    WinQueryFocus
  26609.  ────────────────────────────────────────────────────────────────────────────
  26610.  
  26611.  HWND WinQueryFocus  (hwndDesktop, fLock)
  26612.  
  26613.  HWND  hwndDesktop;                /*desktop handle */
  26614.  
  26615.  BOOL  fLock;                      /*lock/unlock flag */
  26616.  
  26617.  
  26618.  The WinQueryFocus function returns the handle of the window that currently
  26619.  has the focus.
  26620.  
  26621.  
  26622.  Parameters
  26623.  
  26624.  hwndDesktop  Identifies the desktop window. This parameter can be
  26625.  HWND_DESKTOP or the desktop window handle.
  26626.  
  26627.  fLock  This parameter is ignored by MS OS/2 versions 1.2 and later.
  26628.  
  26629.  
  26630.  Return Value
  26631.  
  26632.  The return value is a handle to the focus window or NULL if there is no
  26633.  focus window or an error occurs.
  26634.  
  26635.  
  26636.  See Also
  26637.  
  26638.  WinFocusChange, WinLockWindow, WinQueryActiveWindow, WinSetFocus
  26639.  
  26640.  
  26641.  Changes
  26642.  
  26643.  The fLock parameter is ignored by MS OS/2 versions 1.2 and later.
  26644.  
  26645.  
  26646.  █    WinQueryHelpInstance
  26647.  ────────────────────────────────────────────────────────────────────────────
  26648.  
  26649.  HWND WinQueryHelpInstance  (hwndApp)
  26650.  
  26651.  HWND  hwndApp;                    /*handle of application window */
  26652.  
  26653.  
  26654.  The WinQueryHelpInstance function retrieves the handle of the help instance
  26655.  associated with the given window.
  26656.  
  26657.  
  26658.  Parameters
  26659.  
  26660.  hwndApp  Identifies a window for which the associated help instance is
  26661.  queried.
  26662.  
  26663.  
  26664.  Return Value
  26665.  
  26666.  The return value is the handle of the associated help instance if the
  26667.  function is successful; it is FALSE if an error occurs.
  26668.  
  26669.  
  26670.  Errors
  26671.  
  26672.  Use the WinGetLastError function to retrieve the error value, which may be
  26673.  one of the following:
  26674.  
  26675.       HMERR_INVALID_QUERY_APP_WND
  26676.       HMERR_NO_HELP_INST_IN_CHAIN
  26677.  
  26678.  
  26679.  
  26680.  
  26681.  
  26682.  Comments
  26683.  
  26684.  The function traces the chain of parent windows, starting with the given
  26685.  window, until it finds a frame window with an associated help instance or
  26686.  finds the desktop. If it finds the desktop, it traces the chain of owner
  26687.  windows, starting with the given window, until it finds a frame window with
  26688.  an associated help instance or the desktop.
  26689.  
  26690.  
  26691.  See Also
  26692.  
  26693.  WinAssociateHelpInstance
  26694.  
  26695.  
  26696.  █    WinQueryPresParam
  26697.  ────────────────────────────────────────────────────────────────────────────
  26698.  
  26699.  ULONG WinQueryPresParam  (hwnd, id1, id2, pulId, cbBuf, pbBuf, fs)
  26700.  
  26701.  HWND  hwnd;                       /*window handle */
  26702.  
  26703.  ULONG  id1;                       /*first parameter type to retrieve */
  26704.  
  26705.  ULONG  id2;                       /*second parameter type to retrieve */
  26706.  
  26707.  PULONG  pulId;                    /*pointer to variable for parameter ID
  26708.                                    */
  26709.  
  26710.  ULONG  cbBuf;                     /*buffer length */
  26711.  
  26712.  PVOID  pbBuf;                     /*pointer to buffer for presentation
  26713.                                    parameter */
  26714.  
  26715.  USHORT  fs;                       /*flags */
  26716.  
  26717.  
  26718.  The WinQueryPresParam function retrieves the presentation parameters for a
  26719.  window.
  26720.  
  26721.  
  26722.  Parameters
  26723.  
  26724.  hwnd  Identifies the window that contains the presentation parameters to
  26725.  retrieve.
  26726.  
  26727.  id1  Identifies the first type of presentation parameter to retrieve. If
  26728.  both the id1 and id2 parameters are found, id1 takes precedence and its
  26729.  presentation parameter is returned. This parameter is ignored if it is zero.
  26730.  
  26731.  
  26732.  id2  Identifies the second type of presentation parameter to retrieve. If
  26733.  both the id1 and id2 parameters are found, id1 takes precedence and its
  26734.  presentation parameter is returned. This parameter is ignored if it is zero.
  26735.  
  26736.  
  26737.  pulId  Points to the variable that receives the presentation parameter ID.
  26738.  
  26739.  cbBuf  Specifies the length (in bytes) of the buffer pointed to by the pbBuf
  26740.  parameter.
  26741.  
  26742.  pbBuf  Points to the buffer that receives the presentation parameter.
  26743.  
  26744.  fs  Specifies one or more flags. These can be any combination of the
  26745.  following values:
  26746.  
  26747.  Value                             Meaning
  26748.  ────────────────────────────────────────────────────────────────────────────
  26749.  
  26750.  QPF_NOINHERIT                     Specifies that only the window
  26751.                                    identified by hwnd is to be searched for
  26752.                                    presentation parameters. If this flag is
  26753.                                    not specified, the entire owner-chain of
  26754.                                    the window will be searched.
  26755.  
  26756.  QPF_ID1COLORINDEX                 Specifies that the id1 parameter is a
  26757.                                    color index. The RGB color equivalent is
  26758.                                    returned in the pbBuf parameter.
  26759.  
  26760.  QPF_ID2COLORINDEX                 Specifies that the id2 parameter is a
  26761.                                    color index. The RGB color equivalent is
  26762.                                    returned in the pbBuf parameter.
  26763.  
  26764.  QPF_PURERGBCOLOR                  Specifies that the returned value should
  26765.                                    be a pure RGB color.
  26766.  
  26767.  
  26768.  
  26769.  Return Value
  26770.  
  26771.  The return value is the size (in bytes) of the presentation parameter if the
  26772.  function is successful; it is NULL if no parameter was found or an error
  26773.  occurs.
  26774.  
  26775.  
  26776.  Comments
  26777.  
  26778.  The following parameter types are defined for MS OS/2 versions 1.2 and
  26779.  later:
  26780.  
  26781.  Value                             Meaning
  26782.  ────────────────────────────────────────────────────────────────────────────
  26783.  
  26784.  PP_FOREGROUNDCOLOR                RGB foreground color
  26785.  
  26786.  PP_FOREGROUNDCOLORINDEX           Color index of foreground color
  26787.  
  26788.  PP_BACKGROUNDCOLOR                RGB background color
  26789.  
  26790.  PP_BACKGROUNDCOLORINDEX           Color index of background color
  26791.  
  26792.  PP_HILITEFOREGROUNDCOLOR          RGB color of foreground highlighted area
  26793.  
  26794.  PP_HILITEFOREGROUNDCOLORINDEX     Color index of foreground highlighted
  26795.                                    area .
  26796.  
  26797.  PP_HILITEBACKGROUNDCOLOR          RGB color of background highlighted area
  26798.  
  26799.  PP_HILITEBACKGROUNDCOLORINDEX     Color index of background highlighted
  26800.                                    area .
  26801.  
  26802.  PP_DISABLEDFOREGROUNDCOLOR        RGB foreground disabled color
  26803.  
  26804.  PP_DISABLEDFOREGROUNDCOLORINDEX   Color index of foreground disabled color
  26805.  
  26806.  PP_DISABLEDBACKGROUNDCOLOR        RGB color of background disabled color
  26807.  
  26808.  PP_DISABLEDBACKGROUNDCOLORINDEX   Color index of background disabled color
  26809.  
  26810.  PP_BORDERCOLOR                    RGB color of window border
  26811.  
  26812.  PP_BORDERCOLORINDEX               Color index of window border
  26813.  
  26814.  PP_FONTNAMESIZE                   Font size
  26815.  
  26816.  
  26817.  
  26818.  See Also
  26819.  
  26820.  WinSetPresParam
  26821.  
  26822.  
  26823.  █    WinQueryProfileData
  26824.  ────────────────────────────────────────────────────────────────────────────
  26825.  
  26826.  
  26827.  
  26828.  The WinQueryProfileData function provides compatibility with MS OS/2
  26829.  versions 1.1 and earlier. Applications intended exclusively for MS OS/2
  26830.  versions 1.2 and later should use the PrfQueryProfileData function.
  26831.  
  26832.  
  26833.  █    WinQueryProfileInt
  26834.  ────────────────────────────────────────────────────────────────────────────
  26835.  
  26836.  
  26837.  
  26838.  The WinQueryProfileInt function provides compatibility with MS OS/2 versions
  26839.  1.1 and earlier. Applications intended exclusively for MS OS/2 versions 1.2
  26840.  and later should use the PrfQueryProfileInt function.
  26841.  
  26842.  
  26843.  
  26844.  
  26845.  █    WinQueryProfileSize
  26846.  ────────────────────────────────────────────────────────────────────────────
  26847.  
  26848.  
  26849.  
  26850.  The WinQueryProfileSize function provides compatibility with MS OS/2
  26851.  versions 1.1 and earlier. Applications intended exclusively for MS OS/2
  26852.  versions 1.2 and later should use the PrfQueryProfileSize function.
  26853.  
  26854.  
  26855.  
  26856.  
  26857.  █    WinQueryProfileString
  26858.  ────────────────────────────────────────────────────────────────────────────
  26859.  
  26860.  
  26861.  
  26862.  The WinQueryProfileString function provides compatibility with MS OS/2
  26863.  versions 1.1 and earlier. Applications intended exclusively for MS OS/2
  26864.  versions 1.2 and later should use the PrfQueryProfileString function.
  26865.  
  26866.  
  26867.  
  26868.  
  26869.  █    WinQueryProgramTitles
  26870.  ────────────────────────────────────────────────────────────────────────────
  26871.  
  26872.  
  26873.  
  26874.  The WinQueryProgramTitles function provides compatibility with MS OS/2
  26875.  versions 1.1 and earlier. Applications intended exclusively for MS OS/2
  26876.  versions 1.2 and later should use the PrfQueryProgramTitles function.
  26877.  
  26878.  
  26879.  
  26880.  
  26881.  █    WinQuerySessionTitle
  26882.  ────────────────────────────────────────────────────────────────────────────
  26883.  
  26884.  USHORT WinQuerySessionTitle  (hab, usSession, pszTitle, cbTitle)
  26885.  
  26886.  HAB  hab;                         /*anchor-block handle */
  26887.  
  26888.  USHORT  usSession;                /*screen session */
  26889.  
  26890.  PSZ  pszTitle;                    /*pointer to buffer for title */
  26891.  
  26892.  USHORT  cbTitle;                  /*buffer length */
  26893.  
  26894.  
  26895.  The WinQuerySessionTitle function retrieves the title under which a
  26896.  specified application was started or added to the Task List.
  26897.  
  26898.  
  26899.  Parameters
  26900.  
  26901.  hab  Identifies the anchor block.
  26902.  
  26903.  usSession  Specifies the screen session. For MS OS/2 versions 1.2 and later,
  26904.  this value may be 0 or 1; 0 means the screen session of the caller.
  26905.  
  26906.  pszTitle  Points to the buffer that receives the null-terminated string that
  26907.  specifies the application's title.
  26908.  
  26909.  cbTitle  Specifies the length (in bytes) of the buffer pointed by pszTitle.
  26910.  If the title string is longer than this length, the title will be truncated.
  26911.  
  26912.  
  26913.  
  26914.  Return Value
  26915.  
  26916.  The return value is zero if the function is successful. Otherwise, it is an
  26917.  error value, which may be the following:
  26918.  
  26919.      PMERR_INVALID_SESSION_ID
  26920.  
  26921.  
  26922.  
  26923.  
  26924.  
  26925.  Comments
  26926.  
  26927.  The length of the title is guaranteed not to exceed MAXNAMEL bytes, plus one
  26928.  for the terminating null character. (MAXNAMEL is defined in the MS OS/2
  26929.  include files.)
  26930.  
  26931.  
  26932.  Example
  26933.  
  26934.  This example calls WinQuerySessionTitle to retrieve the application's title,
  26935.  and then sets the title bar of the frame window to that title.
  26936.  
  26937.  CHAR szTitle[MAXNAMEL + 1];
  26938.  
  26939.  WinQuerySessionTitle(hab, 0, szTitle, sizeof(szTitle));
  26940.  WinSetWindowText(hwndFrame, szTitle);
  26941.  
  26942.  
  26943.  
  26944.  
  26945.  
  26946.  See Also
  26947.  
  26948.  WinSetWindowText
  26949.  
  26950.  
  26951.  █    WinQuerySwitchEntry
  26952.  ────────────────────────────────────────────────────────────────────────────
  26953.  
  26954.  USHORT WinQuerySwitchEntry  (hSwitch, pswctl)
  26955.  
  26956.  HSWITCH  hSwitch;                 /*item handle */
  26957.  
  26958.  PSWCNTRL  pswctl;                 /*point to structure with item data */
  26959.  
  26960.  
  26961.  The WinQuerySwitchEntry function obtains a copy of the Task List data for a
  26962.  specific application.
  26963.  
  26964.  
  26965.  Parameters
  26966.  
  26967.  hSwitch  Identifies the Task List item.
  26968.  
  26969.  pswctl  Points to the SWCNTRL data structure that contains information about
  26970.  the specified Task List item. The SWCNTRL structure has the following form:
  26971.  
  26972.  typedef struct _SWCNTRL {
  26973.      HWND     hwnd;
  26974.      HWND     hwndIcon;
  26975.      HPROGRAM hprog;
  26976.      USHORT   idProcess;
  26977.      USHORT   idSession;
  26978.      UCHAR    uchVisibility;
  26979.      UCHAR    fbJump;
  26980.      CHAR     szSwtitle[MAXNAMEL+1];
  26981.      BYTE     fReserved;
  26982.  } SWCNTRL;
  26983.  
  26984.  
  26985.  
  26986.  
  26987.  For a full description, see Chapter 4, "Types, Macros, Structures."
  26988.  
  26989.  
  26990.  Return Value
  26991.  
  26992.  The return value is zero if the function is successful. Otherwise, it is an
  26993.  error value, which may be the following:
  26994.  
  26995.      PMERR_INVALID_SWITCH_HANDLE
  26996.  
  26997.  
  26998.  
  26999.  
  27000.  
  27001.  See Also
  27002.  
  27003.  WinQuerySwitchHandle
  27004.  
  27005.  
  27006.  █    WinQuerySwitchHandle
  27007.  ────────────────────────────────────────────────────────────────────────────
  27008.  
  27009.  HSWITCH WinQuerySwitchHandle  (hwnd, pidProcess)
  27010.  
  27011.  HWND  hwnd;                       /*window handle */
  27012.  
  27013.  PID  pidProcess;                  /*process identifier */
  27014.  
  27015.  
  27016.  The WinQuerySwitchHandle function retrieves the handle of the Task List item
  27017.  of an application.
  27018.  
  27019.  
  27020.  Parameters
  27021.  
  27022.  hwnd  Identifies the frame window of the application. This parameter may be
  27023.  zero if the process identifier is specified in the pidProcess parameter.
  27024.  
  27025.  pidProcess  Specifies the process identifier. This parameter may be zero if
  27026.  the window handle is specified in the hwnd parameter.
  27027.  
  27028.  
  27029.  Return Value
  27030.  
  27031.  The return value is the Task List handle for the specified application if
  27032.  the function is successful or NULL if an error occurs.
  27033.  
  27034.  
  27035.  Comments
  27036.  
  27037.  If both a window handle and a process identifier are supplied, they both
  27038.  must apply to the same application.
  27039.  
  27040.  
  27041.  Example
  27042.  
  27043.  This example calls WinQuerySwitchHandle to get the Task List handle of a
  27044.  frame window, and then calls WinQuerySwitchEntry to retrieve information
  27045.  about that application.
  27046.  
  27047.  HSWITCH hswitch;
  27048.  SWCNTRL swctl;
  27049.  
  27050.  hswitch = WinQuerySwitchHandle(hwndFrame, 0);
  27051.  WinQuerySwitchEntry(hswitch, &swctl);
  27052.  
  27053.  
  27054.  
  27055.  
  27056.  
  27057.  See Also
  27058.  
  27059.  WinQuerySwitchEntry
  27060.  
  27061.  
  27062.  █    WinQuerySwitchList
  27063.  ────────────────────────────────────────────────────────────────────────────
  27064.  
  27065.  USHORT WinQuerySwitchList  (hab, pswblk, cbswblk)
  27066.  
  27067.  HAB  hab;                         /*anchor-block handle */
  27068.  
  27069.  PSWBLOCK  pswblk;                 /*pointer to structure for items */
  27070.  
  27071.  USHORT  cbswblk;                  /*structure length */
  27072.  
  27073.  
  27074.  The WinQuerySwitchList function obtains information about the items in the
  27075.  Task List (the list of programs running in the system).
  27076.  
  27077.  
  27078.  Parameters
  27079.  
  27080.  hab  Identifies the anchor block.
  27081.  
  27082.  pswblk  Points to SWBLOCK structure that receives a description of all the
  27083.  items in the Task List. The SWBLOCK structure has the following form:
  27084.  
  27085.  typedef struct _SWBLOCK {
  27086.      USHORT  cswentry;
  27087.      SWENTRY aswentry[1];
  27088.  } SWBLOCK;
  27089.  
  27090.  
  27091.  
  27092.  
  27093.  For a full description, see Chapter 4, "Types, Macros, Structures."
  27094.  
  27095.  cbswblk  Specifies the size (in bytes) of the SWBLOCK structure. This
  27096.  parameter may be zero to retrieve only the number of Task-list items.
  27097.  
  27098.  
  27099.  Return Value
  27100.  
  27101.  The return value is the current number of items in the Task List if the
  27102.  function is successful or zero if an error occurs.
  27103.  
  27104.  
  27105.  Comments
  27106.  
  27107.  The SWBLOCK structure contains an array of SWENTRY structures. The first
  27108.  array contains information about the Task List window. The second array
  27109.  contains information about the first program in the Task List.
  27110.  
  27111.  
  27112.  Example
  27113.  
  27114.  This example calls WinQuerySwitchList to determine the number of items in
  27115.  the Task List, allocates memory for the required buffer, and calls
  27116.  WinQuerySwitchList again to fill the buffer with the information about each
  27117.  program in the Task List.
  27118.  
  27119.  USHORT cbItems, cbBuf;
  27120.  PSWBLOCK pswblk;
  27121.  SEL sel;
  27122.  
  27123.  cbItems = WinQuerySwitchList(hab, (PSWBLOCK) NULL, 0);
  27124.  cbBuf = (cbItems * sizeof(SWENTRY)) + sizeof(HSWITCH);
  27125.  DosAllocSeg(cbBuf, &sel, SEG_NONSHARED);      /* allocates buffer   */
  27126.  pswblk = MAKEP(sel, 0);
  27127.  WinQuerySwitchList(hab, pswblk, cbBuf);       /* gets struct. array */
  27128.  
  27129.  
  27130.  
  27131.  
  27132.  
  27133.  See Also
  27134.  
  27135.  WinQuerySwitchEntry
  27136.  
  27137.  
  27138.  █    WinQuerySysModalWindow
  27139.  ────────────────────────────────────────────────────────────────────────────
  27140.  
  27141.  HWND WinQuerySysModalWindow  (hwndDesktop, fLock)
  27142.  
  27143.  HWND  hwndDesktop;                /*handle of the desktop */
  27144.  
  27145.  BOOL  fLock;                      /*lock/unlock flag */
  27146.  
  27147.  
  27148.  The WinQuerySysModalWindow function returns the current system modal window.
  27149.  
  27150.  
  27151.  
  27152.  Parameters
  27153.  
  27154.  hwndDesktop  Identifies the desktop window. This parameter can be
  27155.  HWND_DESKTOP or the desktop window handle.
  27156.  
  27157.  fLock  This parameter is ignored by MS OS/2 versions 1.2 and later.
  27158.  
  27159.  
  27160.  Return Value
  27161.  
  27162.  The return value is the handle of the current system modal window. If there
  27163.  is none, the return value is NULL.
  27164.  
  27165.  
  27166.  See Also
  27167.  
  27168.  WinLockWindow, WinSetSysModalWindow
  27169.  
  27170.  
  27171.  Changes
  27172.  
  27173.  The fLock parameter is ignored by MS OS/2 versions 1.2 and later.
  27174.  
  27175.  
  27176.  █    WinQuerySysValue
  27177.  ────────────────────────────────────────────────────────────────────────────
  27178.  
  27179.  LONG WinQuerySysValue  (hwndDesktop, iSysValue)
  27180.  
  27181.  HWND  hwndDesktop;                /*handle of desktop */
  27182.  
  27183.  SHORT  iSysValue;                 /*system value to retrieve */
  27184.  
  27185.  
  27186.  The WinQuerySysValue function retrieves a specified system value.
  27187.  
  27188.  
  27189.  Parameters
  27190.  
  27191.  hwndDesktop  Identifies the desktop window. This parameter can be
  27192.  HWND_DESKTOP or the desktop window handle.
  27193.  
  27194.  iSysValue  Specifies the system value. For a complete list of possible
  27195.  system values, see the following "Comments" section.
  27196.  
  27197.  
  27198.  Return Value
  27199.  
  27200.  The return value is the system value if the function is successful, or zero
  27201.  if an error occurs.
  27202.  
  27203.  
  27204.  Comments
  27205.  
  27206.  The system values can be any of the following values:
  27207.  
  27208.  Value                             Meaning
  27209.  ────────────────────────────────────────────────────────────────────────────
  27210.  
  27211.  SV_CMOUSEBUTTONS                  Specifies the number of mouse buttons: 1,
  27212.                                    2, or 3.
  27213.  
  27214.  SV_MOUSEPRESENT                   Specifies whether the mouse is present.
  27215.                                    A value of TRUE means the mouse is
  27216.                                    present.
  27217.  
  27218.  SV_SWAPBUTTON                     Specifies whether the mouse buttons are
  27219.                                    swapped. A value of TRUE means the mouse
  27220.                                    buttons are swapped.
  27221.  
  27222.  SV_CXDBLCLK                       Specifies the horizontal spacing for a
  27223.                                    mouse double-click. When the horizontal
  27224.                                    distance between two mouse clicks is
  27225.                                    less than this value, the horizontal
  27226.                                    spacing requirement for considering two
  27227.                                    mouse clicks a double-click is met.
  27228.  
  27229.  SV_CYDBLCLK                       Specifies the vertical spacing for a
  27230.                                    mouse double-click. When the vertical
  27231.                                    distance between two mouse clicks is
  27232.                                    less than this value, the vertical
  27233.                                    spacing requirement for considering two
  27234.                                    mouse clicks a double-click is met.
  27235.  
  27236.  SV_DBLCLKTIME                     Specifies the mouse double-click time,
  27237.                                    in milliseconds. When the time between
  27238.                                    two mouse clicks is less than this value,
  27239.                                    the temporal requirement for considering
  27240.                                    two mouse clicks a double-click is met.
  27241.  
  27242.  SV_CXSIZEBORDER                   Specifies the number of pels along the x
  27243.                                    -axis in a window-sizing border.
  27244.  
  27245.  SV_CYSIZEBORDER                   Specifies the number of pels along the y
  27246.                                    -axis in a window-sizing border.
  27247.  
  27248.  SV_ALARM                          Specifies whether a call to the WinAlarm
  27249.                                    function generates a sound. A value of
  27250.                                    TRUE means sound is generated.
  27251.  
  27252.  SV_CURSORRATE                     Specifies the rate at which the cursor
  27253.                                    blinks, in milliseconds. The blink rate
  27254.                                    is the time that the cursor remains
  27255.                                    visible or invisible. Twice this value
  27256.                                    is the time the cursor takes to cycle
  27257.                                    from visibility to invisibility and back.
  27258.  
  27259.  SV_FIRSTSCROLLRATE                Specifies the delay (in milliseconds)
  27260.                                    between clicking and holding down the
  27261.                                    mouse button (when the mouse pointer is
  27262.                                    on a scroll arrow or scroll bar) and the
  27263.                                    beginning of scroll-bar autorepeat
  27264.                                    activity.
  27265.  
  27266.  SV_SCROLLRATE                     Specifies the delay (in milliseconds)
  27267.                                    between scroll-bar autorepeat events. .
  27268.  
  27269.  SV_NUMBEREDLISTS                  Reserved.
  27270.  
  27271.  SV_ERRORFREQ                      Specifies the frequency (in hertz) of a
  27272.                                    WinAlarm function WA_ERROR sound.
  27273.  
  27274.  SV_NOTEFREQ                       Specifies the frequency (in hertz) of a
  27275.                                    WinAlarm function WA_NOTE sound.
  27276.  
  27277.  SV_WARNINGFREQ                    Specifies the frequency (in hertz) of a
  27278.                                    WinAlarm function WA_WARNING sound.
  27279.  
  27280.  SV_ERRORDURATION                  Specifies the duration (in milliseconds)
  27281.                                    of a WinAlarm function WA_ERROR sound.
  27282.  
  27283.  SV_NOTEDURATION                   Specifies the duration (in milliseconds)
  27284.                                    of a WinAlarm function WA_NOTE sound.
  27285.  
  27286.  SV_WARNINGDURATION                Specifies the duration (in milliseconds)
  27287.                                    of a WinAlarm function WA_WARNING sound.
  27288.  
  27289.  SV_CXSCREEN                       Specifies the number of pels along the
  27290.                                    screen's x-axis.
  27291.  
  27292.  SV_CYSCREEN                       Specifies the number of pels along the
  27293.                                    screen's y-axis.
  27294.  
  27295.  SV_CXVSCROLL                      Specifies the number of pels along the x
  27296.                                    -axis of a vertical scroll bar.
  27297.  
  27298.  SV_CYHSCROLL                      Specifies the number of pels along the y
  27299.                                    -axis of a horizontal scroll bar.
  27300.  
  27301.  SV_CXHSCROLLARROW                 Specifies the number of pels along the x
  27302.                                    -axis of a horizontal scroll arrow.
  27303.  
  27304.  SV_CYVSCROLLARROW                 Specifies the number of pels along the y
  27305.                                    -axis of a vertical scroll arrow.
  27306.  
  27307.  SV_CXBORDER                       Specifies the number of pels along the x
  27308.                                    -axis of a window border.
  27309.  
  27310.  SV_CYBORDER                       Specifies the number of pels along the y
  27311.                                    -axis of a window border.
  27312.  
  27313.  SV_CXDLGFRAME                     Specifies the number of pels along the x
  27314.                                    -axis of a dialog-box frame.
  27315.  
  27316.  SV_CYDLGFRAME                     Specifies the number of pels along the y
  27317.                                    -axis of a dialog-box frame.
  27318.  
  27319.  SV_CYTITLEBAR                     Specifies the number of pels along the y
  27320.                                    -axis of a title-bar window.
  27321.  
  27322.  SV_CXHSLIDER                      Specifies the number of pels along the x
  27323.                                    -axis of a horizontal scroll-bar slider.
  27324.  
  27325.  SV_CYVSLIDER                      Specifies the number of pels along the y
  27326.                                    -axis of a vertical scroll-bar slider.
  27327.  
  27328.  SV_CXMINMAXBUTTON                 Specifies the width (in pels) of a
  27329.                                    minimize or maximize button.
  27330.  
  27331.  SV_CYMINMAXBUTTON                 Specifies the height (in pels) of a
  27332.                                    minimize or maximize button.
  27333.  
  27334.  SV_CYMENU                         Specifies the height (in pels) of a menu.
  27335.  
  27336.  SV_CXFULLSCREEN                   Specifies the number of pels along the x
  27337.                                    -axis of the client window of a
  27338.                                    maximized frame window.
  27339.  
  27340.  SV_CYFULLSCREEN                   Specifies the number of pels along the y
  27341.                                    -axis of the client window of a
  27342.                                    maximized frame window.
  27343.  
  27344.  SV_CXICON                         Specifies the number of pels along an
  27345.                                    icon's x-axis.
  27346.  
  27347.  SV_CYICON                         Specifies the number of pels along an
  27348.                                    icon's y-axis.
  27349.  
  27350.  SV_CXPOINTER                      Specifies the number of pels along the
  27351.                                    mouse pointer's x-axis.
  27352.  
  27353.  SV_CYPOINTER                      Specifies the number of pels along the
  27354.                                    mouse pointer's y-axis.
  27355.  
  27356.  SV_DEBUG                          Reserved.
  27357.  
  27358.  SV_CURSORLEVEL                    Specifies the cursor display count. The
  27359.                                    cursor is visible only when the display
  27360.                                    count is zero.
  27361.  
  27362.  SV_POINTERLEVEL                   Specifies the mouse-pointer display
  27363.                                    count. The mouse is visible only when
  27364.                                    the display count is zero.
  27365.  
  27366.  SV_TRACKRECTLEVEL                 Specifies the tracking-rectangle display
  27367.                                    count. The tracking rectangle is visible
  27368.                                    only when the display count is zero.
  27369.  
  27370.  SV_CTIMERS                        Specifies the number of available timers.
  27371.  
  27372.  SV_CXBYTEALIGN                    Specifies a horizontal alignment that is
  27373.                                    more efficient for the device driver.
  27374.  
  27375.  SV_CYBYTEALIGN                    Specifies a vertical alignment that is
  27376.                                    more efficient for the device driver.
  27377.  
  27378.  SV_EXTRAKEYBEEP                   Specifies whether beep is turned on for
  27379.                                    extended keys (keys not on an IBM PS/2
  27380.                                    or compatible keyboard).
  27381.  
  27382.  SV_SETLIGHTS                      Specifies if the system controls the
  27383.                                    keyboard indicator lights.
  27384.  
  27385.  SV_INSERTMODE                     Specifies if insert mode is on or off
  27386.                                    for entry-field controls.
  27387.  
  27388.  SV_MENUROLLDOWNDELAY              Specifies the delay for menu roll down.
  27389.  
  27390.  SV_MENUROLLUPDELAY                Specifies the delay for menu roll up.
  27391.  
  27392.  SV_ALTMNEMONIC                    Specifies if the Alt key is allowed as a
  27393.                                    mnemonic.
  27394.  
  27395.  SV_TASKLISTMOUSEACCESS            Specifies if the Task List can be
  27396.                                    accessed by the right mouse button.
  27397.  
  27398.  SV_CSYSVALUES                     Specifies the number of system values.
  27399.  
  27400.  
  27401.  
  27402.  See Also
  27403.  
  27404.  WinSetSysValue
  27405.  
  27406.  
  27407.  Changes
  27408.  
  27409.  The following system values have been added:
  27410.  
  27411.       SV_EXTRAKEYBEEP
  27412.       SV_SETLIGHTS
  27413.       SV_INSERTMODE
  27414.       SV_MENUROLLDOWNDELAY
  27415.       SV_MENUROLLUPDELAY
  27416.       SV_ALTMNEMONIC
  27417.       SV_TASKLISTMOUSEACCESS
  27418.  
  27419.  
  27420.  
  27421.  
  27422.  
  27423.  █    WinQueryTaskSizePos
  27424.  ────────────────────────────────────────────────────────────────────────────
  27425.  
  27426.  USHORT WinQueryTaskSizePos  (hab, usSession, pswp)
  27427.  
  27428.  HAB  hab;                         /*anchor-block handle */
  27429.  
  27430.  USHORT  usSession;                /*screen session */
  27431.  
  27432.  PSWP  pswp;                       /*pointer to structure for defaults */
  27433.  
  27434.  
  27435.  The WinQueryTaskSizePos function retrieves the default size, position, and
  27436.  status for the first frame window of a newly started application.
  27437.  
  27438.  
  27439.  Parameters
  27440.  
  27441.  hab  Identifies the anchor block.
  27442.  
  27443.  usSession  Specifies the screen session. For MS OS/2 versions 1.2 and later,
  27444.  this value can be 0 or 1; 0 specifies the screen session of the caller.
  27445.  
  27446.  pswp  Points to the SWP structure that receives the default size, position,
  27447.  and status for the first frame window of the application. The SWP structure
  27448.  has the following form:
  27449.  
  27450.  typedef struct _SWP {
  27451.      USHORT fs;
  27452.      SHORT  cy;
  27453.      SHORT  cx;
  27454.      SHORT  y;
  27455.      SHORT  x;
  27456.      HWND   hwndInsertBehind;
  27457.      HWND   hwnd;
  27458.  } SWP;
  27459.  
  27460.  
  27461.  
  27462.  
  27463.  For a full description, see Chapter 4, "Types, Macros, Structures."
  27464.  
  27465.  
  27466.  Return Value
  27467.  
  27468.  The return value is zero if the function is successful. Otherwise, it is an
  27469.  error value, which may be the following:
  27470.  
  27471.       PMERR_INVALID_SESSION_ID
  27472.  
  27473.  
  27474.  
  27475.  
  27476.  
  27477.  See Also
  27478.  
  27479.  WinQueryWindowPos
  27480.  
  27481.  
  27482.  █    WinQueryWindow
  27483.  ────────────────────────────────────────────────────────────────────────────
  27484.  
  27485.  HWND WinQueryWindow  (hwnd, cmd, fLock)
  27486.  
  27487.  HWND  hwnd;                       /*handle of the window */
  27488.  
  27489.  SHORT  cmd;                       /*which window to retrieve */
  27490.  
  27491.  BOOL  fLock;                      /*lock/unlock flag */
  27492.  
  27493.  
  27494.  The WinQueryWindow function retrieves the handle of a window that has a
  27495.  specified relationship to a specified window.
  27496.  
  27497.  If WinQueryWindow is used to enumerate windows of other threads, it is not
  27498.  guaranteed that all the windows are enumerated, because the Z ordering of
  27499.  the windows may change during the enumeration. The WinGetNextWindow function
  27500.  must be used for this purpose.
  27501.  
  27502.  
  27503.  Parameters
  27504.  
  27505.  hwnd  Identifies a window. The window handle retrieved is relative to this
  27506.  window, based on the value in the cmd parameter.
  27507.  
  27508.  cmd  Specifies which window to retrieve. The following are the possible
  27509.  values:
  27510.  
  27511.  Value                             Meaning
  27512.  ────────────────────────────────────────────────────────────────────────────
  27513.  
  27514.  QW_NEXT                           Next window in Z order (window below).
  27515.  
  27516.  QW_PREV                           Previous window in Z order (window
  27517.                                    above).
  27518.  
  27519.  QW_TOP                            Topmost child window.
  27520.  
  27521.  QW_BOTTOM                         Bottommost child window.
  27522.  
  27523.  QW_OWNER                          Owner of the window.
  27524.  
  27525.  QW_PARENT                         Parent of window; HWND_OBJECT if object
  27526.                                    window.
  27527.  
  27528.  QW_NEXTTOP                        Next main window in the enumeration
  27529.                                    order defined for the ALT+ESCAPE
  27530.                                    function of the user interface.
  27531.  
  27532.  QW_PREVTOP                        Previous main window, in the enumeration
  27533.                                    order defined by QW_NEXTTOP.
  27534.  
  27535.  QW_FRAMEOWNER                     Returns the owner of hwnd, normalized so
  27536.                                    that it shares the same parent as hwnd.
  27537.  
  27538.  
  27539.  
  27540.  fLock  This parameter is ignored by MS OS/2 versions 1.2 and later.
  27541.  
  27542.  
  27543.  Return Value
  27544.  
  27545.  The return value is the handle of the window related to the window
  27546.  identified by the hwnd parameter.
  27547.  
  27548.  
  27549.  See Also
  27550.  
  27551.  WinGetNextWindow, WinLockWindow
  27552.  
  27553.  
  27554.  Changes
  27555.  
  27556.  The fLock parameter is ignored by MS OS/2 versions 1.2 and later.
  27557.  
  27558.  
  27559.  █    WinQueryWindowLockCount
  27560.  ────────────────────────────────────────────────────────────────────────────
  27561.  
  27562.  SHORT WinQueryWindowLockCount  (hwnd)
  27563.  
  27564.  HWND  hwnd;                       /*window handle */
  27565.  
  27566.  
  27567.  This function exists for compatibility with MS OS/2 version 1.1. It is not
  27568.  used in MS OS/2 versions 1.2 and later.
  27569.  
  27570.  
  27571.  Changes
  27572.  
  27573.  This function is not used in MS OS/2 versions 1.2 and later.
  27574.  
  27575.  
  27576.  █    WinRegisterClass
  27577.  ────────────────────────────────────────────────────────────────────────────
  27578.  
  27579.  BOOL WinRegisterClass  (hab, pszClassName, pfnWndProc, flStyle,
  27580.  cbWindowData)
  27581.  
  27582.  HAB  hab;                         /*handle of anchor block */
  27583.  
  27584.  PSZ  pszClassName;                /*pointer to class name */
  27585.  
  27586.  PFNWP  pfnWndProc;                /*address of window procedure */
  27587.  
  27588.  ULONG  flStyle;                   /*window-style flags */
  27589.  
  27590.  USHORT  cbWindowData;             /*amount of reserved data */
  27591.  
  27592.  
  27593.  
  27594.  
  27595.  The WinRegisterClass function registers a window class.
  27596.  
  27597.  When an application registers a private class with the window procedure in a
  27598.  dynamic-link library, the application must resolve the window-procedure
  27599.  address before calling WinRegisterClass.
  27600.  
  27601.  Private classes are deleted when the process that registers them terminates.
  27602.  
  27603.  
  27604.  
  27605.  Parameters
  27606.  
  27607.  hab  Identifies the anchor block.
  27608.  
  27609.  pszClassName  Points to a null-terminated string that specifies the name of
  27610.  the window class. The string can be either a name specified by an
  27611.  application or the name of one of the following preregistered classes:
  27612.  
  27613.  Class                             Description
  27614.  ────────────────────────────────────────────────────────────────────────────
  27615.  
  27616.  WC_BUTTON                         A button, which can be a push button, a
  27617.                                    radio button, a check box, or a user
  27618.                                    button.
  27619.  
  27620.  WC_COMBOBOX                       A combination entry field and list box.
  27621.  
  27622.  WC_ENTRYFIELD                     An entry field that allows single line
  27623.                                    text editing.
  27624.  
  27625.  WC_FRAME                          A standard frame window.
  27626.  
  27627.  WC_LISTBOX                        A list box that displays items in a list
  27628.                                    that can be scrolled.
  27629.  
  27630.  WC_MLE                            A multiple-line entry field.
  27631.  
  27632.  WC_MENU                           A menu, including the menu bar and the
  27633.                                    menus that can be selected from it.
  27634.  
  27635.  WC_SCROLLBAR                      A scroll bar that allows a user to
  27636.                                    scroll the contents of a window.
  27637.  
  27638.  WC_STATIC                         A static control that displays text,
  27639.                                    icon, or bitmap data.
  27640.  
  27641.  WC_TITLEBAR                       A title bar that displays the title of a
  27642.                                    window across the top of the frame and
  27643.                                    allows the user to drag the frame window
  27644.                                    to a new location.
  27645.  
  27646.  
  27647.  
  27648.  pfnWndProc  Points to the window procedure. This value can be NULL if the
  27649.  application does not provide a window procedure. An application written in a
  27650.  language that does not allow the system to call the application's window
  27651.  procedure (for example, COBOL or FORTRAN) should also use NULL for this
  27652.  parameter. For more information, see WinGetDlgMsg.
  27653.  
  27654.  flStyle  Specifies the default window style, which can be any of the
  27655.  standard CS class styles or any styles that are defined with the class
  27656.  specified by pszClassName. These styles can be augmented when a window of
  27657.  this class is created. A public window class is created if the CS_PUBLIC
  27658.  style is specified; otherwise, a private class is created. Public classes
  27659.  are available from any process for creating a window. Private classes are
  27660.  available only to the registering process.
  27661.  
  27662.  The following list describes the standard classes:
  27663.  
  27664.  Style                             Meaning
  27665.  ────────────────────────────────────────────────────────────────────────────
  27666.  
  27667.  CS_CLIPCHILDREN                   Sets the WS_CLIPCHILDREN style for
  27668.                                    windows created by using this class.
  27669.  
  27670.  CS_CLIPSIBLINGS                   Sets the WS_CLIPSIBLINGS style for
  27671.                                    windows created by using this class.
  27672.  
  27673.  CS_FRAME                          Identifies windows created by using this
  27674.                                    class as frame windows.
  27675.  
  27676.  CS_HITTEST                        Directs the system to send a WM_HITTEST
  27677.                                    message to a window of this class
  27678.                                    whenever the mouse moves in the window.
  27679.  
  27680.  CS_MOVENOTIFY                     Directs the system to send a WM_MOVE
  27681.                                    message to the window whenever the
  27682.                                    window moves.
  27683.  
  27684.  CS_PARENTCLIP                     Sets the WS_PARENTCLIP style for windows
  27685.                                    created by using this class.
  27686.  
  27687.  CS_PUBLIC                         Creates a public window class.
  27688.  
  27689.  CS_SAVEBITS                       Sets the WS_SAVEBITS style for windows
  27690.                                    created by using this class.
  27691.  
  27692.  CS_SIZEREDRAW                     Directs the system to invalidate the
  27693.                                    entire window whenever the size of the
  27694.                                    window changes.
  27695.  
  27696.  CS_SYNCPAINT                      Sets the WS_SYNCPAINT style for windows
  27697.                                    created by using this class.
  27698.  
  27699.  
  27700.  
  27701.  cbWindowData  Specifies the number of bytes of storage reserved for use by
  27702.  applications for each window created with the specified class.
  27703.  
  27704.  
  27705.  Return Value
  27706.  
  27707.  The return value is TRUE if the function is successful or FALSE if an error
  27708.  occurs.
  27709.  
  27710.  
  27711.  Comments
  27712.  
  27713.  If a private class is registered with the same name as one that already
  27714.  exists, the parameters replace the old class parameters.
  27715.  
  27716.  
  27717.  Example
  27718.  
  27719.  This example calls WinRegisterClass to register a class or returns FALSE if
  27720.  an error occurs.
  27721.  
  27722.  HAB hab;
  27723.  CHAR szClassName[] = "Generic"; /* window class name      */
  27724.  
  27725.  if (!WinRegisterClass(hab,   /* anchor-block handle       */
  27726.          szClassName,         /* class name                */
  27727.          GenericWndProc,      /* window procedure          */
  27728.          0L,                  /* window style              */
  27729.          0))                  /* amount of reserved memory */
  27730.      return (FALSE);
  27731.  
  27732.  
  27733.  
  27734.  
  27735.  
  27736.  See Also
  27737.  
  27738.  WinGetDlgMsg, WinQueryClassInfo, WinQueryClassName, WinQueryWindowPtr,
  27739.  WinQueryWindowULong, WinQueryWindowUShort
  27740.  
  27741.  
  27742.  Changes
  27743.  
  27744.  The constants WC_COMBOBOX and WC_MLE have been added to the list of
  27745.  preregistered classes.
  27746.  
  27747.  
  27748.  █    WinReleasePS
  27749.  ────────────────────────────────────────────────────────────────────────────
  27750.  
  27751.  BOOL WinReleasePS  (hps)
  27752.  
  27753.  HPS  hps;                         /*presentation-space handle */
  27754.  
  27755.  
  27756.  The WinReleasePS function releases a cached presentation space obtained by
  27757.  using the WinGetClipPS, WinGetPS, or WinGetScreenPS function.
  27758.  
  27759.  Only a cached presentation space can be released using this function. The
  27760.  presentation space is returned to the cache for reuse. The
  27761.  presentation-space handle should not be used following this function.
  27762.  
  27763.  
  27764.  Parameters
  27765.  
  27766.  hps  Identifies the cached presentation space to release.
  27767.  
  27768.  
  27769.  Return Value
  27770.  
  27771.  The return value is TRUE if the function is successful or FALSE if an error
  27772.  occurs.
  27773.  
  27774.  
  27775.  Comments
  27776.  
  27777.  Before an application terminates, it must call WinReleasePS to release any
  27778.  cached presentation spaces obtained.
  27779.  
  27780.  
  27781.  Example
  27782.  
  27783.  This example processes an application-defined message (IDM_FILL). It calls
  27784.  WinGetPS to get a presentation space to the entire window. It gets the
  27785.  dimensions of the current window, fills the window, and calls WinReleasePS
  27786.  to release the presentation space.
  27787.  
  27788.  case IDM_FILL:
  27789.      hps = WinGetPS(hwnd);              /* gets ps for entire window  */
  27790.      WinQueryWindowRect(hwnd, &rcl);    /* gets window dimensions     */
  27791.      WinFillRect(hps, &rcl, CLR_WHITE); /* clears entire window       */
  27792.      WinReleasePS(hps);                 /* releases ps                */
  27793.  
  27794.  
  27795.  
  27796.  
  27797.  
  27798.  See Also
  27799.  
  27800.  WinGetClipPS, WinGetPS, WinGetScreenPS
  27801.  
  27802.  
  27803.  Corrections
  27804.  
  27805.  The WinReleasePS function is used to release any cached presentation space,
  27806.  including those created with the WinGetClipPS and WinGetScreenPS functions.
  27807.  
  27808.  
  27809.  
  27810.  █    WinRemovePresParam
  27811.  ────────────────────────────────────────────────────────────────────────────
  27812.  
  27813.  BOOL WinRemovePresParam  (hwnd, id)
  27814.  
  27815.  HWND  hwnd;                       /*window handle */
  27816.  
  27817.  ULONG  id;                        /*presentation parameter to remove */
  27818.  
  27819.  
  27820.  The WinRemovePresParam function removes a presentation parameter.
  27821.  
  27822.  
  27823.  Parameters
  27824.  
  27825.  hwnd  Identifies the window that contains the presentation parameters to
  27826.  remove.
  27827.  
  27828.  id  Identifies the presentation parameter to remove. It may be one of the
  27829.  following values:
  27830.  
  27831.  Value                             Meaning
  27832.  ────────────────────────────────────────────────────────────────────────────
  27833.  
  27834.  PP_FOREGROUNDCOLOR                RGB foreground color
  27835.  
  27836.  PP_FOREGROUNDCOLORINDEX           Color index of foreground color
  27837.  
  27838.  PP_BACKGROUNDCOLOR                RGB background color
  27839.  
  27840.  PP_BACKGROUNDCOLORINDEX           Color index of background color
  27841.  
  27842.  PP_HILITEFOREGROUNDCOLOR          RGB color of foreground highlighted area
  27843.  
  27844.  PP_HILITEFOREGROUNDCOLORINDEX     Color index of foreground highlighted
  27845.                                    area
  27846.  
  27847.  PP_HILITEBACKGROUNDCOLOR          RGB color of background highlighted area
  27848.  
  27849.  PP_HILITEBACKGROUNDCOLORINDEX     Color index of background highlighted
  27850.                                    area
  27851.  
  27852.  PP_DISABLEDFOREGROUNDCOLOR        RGB foreground disabled color
  27853.  
  27854.  PP_DISABLEDFOREGROUNDCOLORINDEX   Color index of foreground disabled color
  27855.  
  27856.  PP_DISABLEDBACKGROUNDCOLOR        RGB color of background disabled color
  27857.  
  27858.  PP_DISABLEDBACKGROUNDCOLORINDEX   Color index of background disabled color
  27859.  
  27860.  PP_BORDERCOLOR                    RGB color of window border
  27861.  
  27862.  PP_BORDERCOLORINDEX               Color index of window border
  27863.  
  27864.  PP_FONTNAMESIZE                   Font size
  27865.  
  27866.  
  27867.  
  27868.  Return Value
  27869.  
  27870.  The return value is TRUE if the function is successful or FALSE if an error
  27871.  occurs.
  27872.  
  27873.  
  27874.  Comments
  27875.  
  27876.  When a presentation parameter is removed, a WM_PRESPARAMCHANGED message is
  27877.  sent to all windows owned by the window calling the WinSetPresParam
  27878.  function.
  27879.  
  27880.  
  27881.  See Also
  27882.  
  27883.  WinQueryPresParam, WinSetPresParam
  27884.  
  27885.  
  27886.  █    WinSetPresParam
  27887.  ────────────────────────────────────────────────────────────────────────────
  27888.  
  27889.  BOOL WinSetPresParam  (hwnd, id, cbParam, pbParam)
  27890.  
  27891.  HWND  hwnd;                       /*window handle */
  27892.  
  27893.  ULONG  id;                        /*presentation parameter */
  27894.  
  27895.  ULONG  cbParam;                   /*presentation-parameter size */
  27896.  
  27897.  PVOID  pbParam;                   /*pointer to presentation parameter */
  27898.  
  27899.  
  27900.  The WinSetPresParam function sets a presentation parameter.
  27901.  
  27902.  
  27903.  Parameters
  27904.  
  27905.  hwnd  Identifies the window that contains the presentation parameters to
  27906.  set.
  27907.  
  27908.  id  Identifies the presentation parameter to set. It may be one of the
  27909.  following values:
  27910.  
  27911.  Value                             Meaning
  27912.  ────────────────────────────────────────────────────────────────────────────
  27913.  
  27914.  PP_FOREGROUNDCOLOR                RGB foreground color
  27915.  
  27916.  PP_FOREGROUNDCOLORINDEX           Color index of foreground color
  27917.  
  27918.  PP_BACKGROUNDCOLOR                RGB background color
  27919.  
  27920.  PP_BACKGROUNDCOLORINDEX           Color index of background color
  27921.  
  27922.  PP_HILITEFOREGROUNDCOLOR          RGB color of foreground highlighted area
  27923.  
  27924.  PP_HILITEFOREGROUNDCOLORINDEX     Color index of foreground highlighted
  27925.                                    area
  27926.  
  27927.  PP_HILITEBACKGROUNDCOLOR          RGB color of background highlighted area
  27928.  
  27929.  PP_HILITEBACKGROUNDCOLORINDEX     Color index of background highlighted
  27930.                                    area
  27931.  
  27932.  PP_DISABLEDFOREGROUNDCOLOR        RGB foreground disabled color
  27933.  
  27934.  PP_DISABLEDFOREGROUNDCOLORINDEX   Color index of foreground disabled color
  27935.  
  27936.  PP_DISABLEDBACKGROUNDCOLOR        RGB color of background disabled color
  27937.  
  27938.  PP_DISABLEDBACKGROUNDCOLORINDEX   Color index of background disabled color
  27939.  
  27940.  PP_BORDERCOLOR                    RGB color of window border
  27941.  
  27942.  PP_BORDERCOLORINDEX               Color index of window border
  27943.  
  27944.  PP_FONTNAMESIZE                   Font size
  27945.  
  27946.  
  27947.  
  27948.  cbParam  Specifies the length (in bytes) of the buffer pointed to by the
  27949.  pbParam parameter.
  27950.  
  27951.  pbParam  Points to the buffer that contains the presentation parameter.
  27952.  
  27953.  
  27954.  Return Value
  27955.  
  27956.  The return value is TRUE if the function is successful or FALSE if an error
  27957.  occurs.
  27958.  
  27959.  
  27960.  Comments
  27961.  
  27962.  When a presentation parameter is set, a WM_PRESPARAMCHANGED message is sent
  27963.  to all windows owned by the window calling the WinSetPresParam function.
  27964.  
  27965.  
  27966.  See Also
  27967.  
  27968.  WinQueryPresParam, WinRemovePresParam
  27969.  
  27970.  
  27971.  █    WinSetSysColors
  27972.  ────────────────────────────────────────────────────────────────────────────
  27973.  
  27974.  BOOL WinSetSysColors  (hwndDesktop, flOptions, flFormat, clrFirst, cclr,
  27975.  pclr)
  27976.  
  27977.  HWND  hwndDesktop;                /*handle of the desktop */
  27978.  
  27979.  ULONG  flOptions;                 /*color options */
  27980.  
  27981.  ULONG  flFormat;                  /*format options */
  27982.  
  27983.  COLOR  clrFirst;                  /*first color to set */
  27984.  
  27985.  ULONG  cclr;                      /*number of colors to set */
  27986.  
  27987.  PCOLOR  pclr;                     /*address of color definitions */
  27988.  
  27989.  
  27990.  The WinSetSysColors function sets system color values. This function sends a
  27991.  WM_SYSCOLORCHANGE message to all main windows in the system to indicate that
  27992.  the colors have changed. When this message is received, applications that
  27993.  depend on the system colors can query the new color values by using the
  27994.  WinQuerySysColor function.
  27995.  
  27996.  After the WM_SYSCOLORCHANGE messages are sent, all windows in the system are
  27997.  invalidated so that they will be redrawn with the new system colors.
  27998.  
  27999.  WinSetSysColors does not write any system color changes to the os2.ini file.
  28000.  
  28001.  
  28002.  Parameters
  28003.  
  28004.  hwndDesktop  Identifies the desktop window. This parameter can be
  28005.  HWND_DESKTOP or the desktop window handle.
  28006.  
  28007.  flOptions  Specifies an option which can be one of the constants in the
  28008.  following list. In order to use these constants, you must define the
  28009.  INCL_GPILOGCOLORTABLE include constant before specifying the os2.h header
  28010.  file.
  28011.  
  28012.  Value                             Meaning
  28013.  ────────────────────────────────────────────────────────────────────────────
  28014.  
  28015.  LCOL_PURECOLOR                    Indicates that color dithering should
  28016.                                    not be used to create colors that are
  28017.                                    not available in the physical palette.
  28018.                                    If this option is set, only pure colors
  28019.                                    will be used and no dithering will be
  28020.                                    done.
  28021.  
  28022.  LCOL_RESET                        Indicates that the system colors are all
  28023.                                    to be reset to the default values before
  28024.                                    processing the remainder of the data in
  28025.                                    this function.
  28026.  
  28027.  flFormat  Specifies the format of entries in the table. This parameter may
  28028.  be one of the constants in the following list. In order to use these
  28029.  constants, you must define the INCL_GPILOGCOLORTABLE include constant before
  28030.  specifying the os2.h header file.
  28031.  
  28032.  Value                             Meaning
  28033.  ────────────────────────────────────────────────────────────────────────────
  28034.  
  28035.  LCOLF_CONSECRGB                   Array of RGB values that correspond to
  28036.                                    color indices. Each entry is 4 bytes.
  28037.  
  28038.  LCOLF_INDRGB                      Array of (index, RGB) values. Each pair
  28039.                                    of entries is 8 bytes (4 bytes index and
  28040.                                    4 bytes color value).
  28041.  
  28042.  
  28043.  
  28044.  clrFirst  Specifies the starting system color index (this parameter is only
  28045.  relevant for the LCOLF_CONSECRGB format). The following system color indices
  28046.  are defined (each successive index is one larger than its predecessor):
  28047.  
  28048.  Value                             Meaning
  28049.  ────────────────────────────────────────────────────────────────────────────
  28050.  
  28051.  SYSCLR_BUTTONLIGHT                Light button
  28052.  
  28053.  SYSCLR_BUTTONMIDDLE               Middle button
  28054.  
  28055.  SYSCLR_BUTTONDARK                 Dark button
  28056.  
  28057.  SYSCLR_BUTTONDEFAULT              Default button
  28058.  
  28059.  SYSCLR_TITLEBOTTOM                Bottom title
  28060.  
  28061.  SYSCLR_SHADOW                     Shadow
  28062.  
  28063.  SYSCLR_ICONTEXT                   Icon text
  28064.  
  28065.  SYSCLR_DIALOGBACKGROUND           Dialog-box background
  28066.  
  28067.  SYSCLR_HILITEFOREGROUND           Foreground highlight
  28068.  
  28069.  SYSCLR_HILITEBACKGROUND           Background highlight
  28070.  
  28071.  SYSCLR_INACTIVETITLETEXTBGND      Inactive title-text background
  28072.  
  28073.  SYSCLR_ACTIVETITLETEXTBGND        Active title-text background
  28074.  
  28075.  SYSCLR_INACTIVETITLETEXT          Inactive title-text
  28076.  
  28077.  SYSCLR_ACTIVETITLETEXT            Active title-text
  28078.  
  28079.  SYSCLR_OUTPUTTEXT                 Output text
  28080.  
  28081.  SYSCLR_WINDOWSTATICTEXT           Static text
  28082.  
  28083.  SYSCLR_SCROLLBAR                  Scroll bar
  28084.  
  28085.  SYSCLR_BACKGROUND                 Screen background
  28086.  
  28087.  SYSCLR_ACTIVETITLE                Title bar of active window
  28088.  
  28089.  SYSCLR_INACTIVETITLE              Title bar of inactive window
  28090.  
  28091.  SYSCLR_MENU                       Menu background
  28092.  
  28093.  SYSCLR_WINDOW                     Window background
  28094.  
  28095.  SYSCLR_WINDOWFRAME                Window border line
  28096.  
  28097.  SYSCLR_MENUTEXT                   Menu text
  28098.  
  28099.  SYSCLR_WINDOWTEXT                 Window text
  28100.  
  28101.  SYSCLR_TITLETEXT                  Title text
  28102.  
  28103.  SYSCLR_ACTIVEBORDER               Border fill of active window
  28104.  
  28105.  SYSCLR_INACTIVEBORDER             Border fill of inactive window
  28106.  
  28107.  SYSCLR_APPWORKSPACE               Background of certain main windows
  28108.  
  28109.  SYSCLR_HELPBACKGROUND             Background of help panels
  28110.  
  28111.  SYSCLR_HELPTEXT                   Help text
  28112.  
  28113.  SYSCLR_HELPHILITE                 Highlight of help text
  28114.  
  28115.  
  28116.  
  28117.  cclr  Specifies the number of elements supplied in pclr. This parameter may
  28118.  be zero if, for example, the color table is merely to be reset to the
  28119.  default. For LCOLF_INDRGB, this parameter must be an even number. The
  28120.  constant SYSCLR_CSYSCOLORS is set to the total number of system colors.
  28121.  
  28122.  pclr  Specifies the start address of the application data area containing
  28123.  the color-table definition data. The format depends on the value of the
  28124.  flFormat parameter. Each color value is a 4-byte integer. The low byte is
  28125.  the blue intensity value (0x000000FF), the second byte is the green
  28126.  intensity value (0x0000FF00), and the third byte is the red intensity value
  28127.  (0x00FF0000). The intensity for each color may range between 0 and 255.
  28128.  
  28129.  
  28130.  Return Value
  28131.  
  28132.  The return value is TRUE if the function is successful or FALSE if an error
  28133.  occurs.
  28134.  
  28135.  
  28136.  See Also
  28137.  
  28138.  WinQuerySysColor
  28139.  
  28140.  
  28141.  Changes
  28142.  
  28143.  The following system colors have been added:
  28144.  
  28145.       SYSCLR_BUTTONLIGHT
  28146.       SYSCLR_BUTTONMIDDLE
  28147.       SYSCLR_BUTTONDARK
  28148.       SYSCLR_BUTTONDEFAULT
  28149.       SYSCLR_TITLEBOTTOM
  28150.       SYSCLR_SHADOW
  28151.       SYSCLR_ICONTEXT
  28152.       SYSCLR_DIALOGBACKGROUND
  28153.       SYSCLR_HILITEFOREGROUND
  28154.       SYSCLR_HILITEBACKGROUND
  28155.       SYSCLR_INACTIVETITLETEXTBGND
  28156.       SYSCLR_ACTIVETITLETEXTBGND
  28157.       SYSCLR_INACTIVETITLETEXT
  28158.       SYSCLR_ACTIVETITLETEXT
  28159.       SYSCLR_OUTPUTTEXT
  28160.  
  28161.  
  28162.  
  28163.  
  28164.  
  28165.  Corrections
  28166.  
  28167.  The system colors were listed alphabetically instead of by numerical order.
  28168.  The numerical order is important because it is used to determine the
  28169.  starting color to change when LCOLF_CONSECRGB is specified for flFormat.
  28170.  
  28171.  In order to use the LCOL_ and LCOLF_ constants, you must define the
  28172.  INCL_GPILOGCOLORTABLE include constant before specifying the os2.h header
  28173.  file.
  28174.  
  28175.  
  28176.  █    WinSetSysValue
  28177.  ────────────────────────────────────────────────────────────────────────────
  28178.  
  28179.  BOOL WinSetSysValue  (hwndDesktop, iSysValue, lValue)
  28180.  
  28181.  HWND  hwndDesktop;                /*handle of desktop window */
  28182.  
  28183.  SHORT  iSysValue;                 /*system value to change */
  28184.  
  28185.  LONG  lValue;                     /*new system value */
  28186.  
  28187.  
  28188.  The WinSetSysValue function sets the system value.
  28189.  
  28190.  
  28191.  Parameters
  28192.  
  28193.  hwndDesktop  Identifies the desktop window. This parameter can be
  28194.  HWND_DESKTOP or the desktop window handle.
  28195.  
  28196.  iSysValue  Specifies the system value to set. The following system values
  28197.  may be set:
  28198.  
  28199.  Value                             Meaning
  28200.  ────────────────────────────────────────────────────────────────────────────
  28201.  
  28202.  SV_SWAPBUTTON                     Specifies whether the mouse buttons are
  28203.                                    swapped. A value of TRUE means the mouse
  28204.                                    buttons are swapped.
  28205.  
  28206.  SV_CXDBLCLK                       Specifies the horizontal spacing for a
  28207.                                    mouse double-click. When the horizontal
  28208.                                    distance between two mouse clicks is
  28209.                                    less than this value, the horizontal
  28210.                                    spacing requirement is met for two mouse
  28211.                                    clicks to qualify as a double-click.
  28212.  
  28213.  SV_CYDBLCLK                       Specifies the vertical spacing for a
  28214.                                    mouse double-click. When the vertical
  28215.                                    distance between two mouse clicks is
  28216.                                    less than this value, the vertical
  28217.                                    spacing requirement is met for two mouse
  28218.                                    clicks to qualify as a double-click.
  28219.  
  28220.  SV_DBLCLKTIME                     Specifies the mouse double-click time,
  28221.                                    in milliseconds. When the time between
  28222.                                    two mouse clicks is less than this value,
  28223.                                    the temporal requirement is met for two
  28224.                                    mouse clicks to qualify as a
  28225.                                    double-click.
  28226.  
  28227.  SV_CXSIZEBORDER                   Specifies the number of pels along the x
  28228.                                    -axis in a window-sizing border.
  28229.  
  28230.  SV_CYSIZEBORDER                   Specifies the number of pels along the y
  28231.                                    -axis in a window-sizing border.
  28232.  
  28233.  SV_ALARM                          Specifies whether a call to the WinAlarm
  28234.                                    function generates a sound. A value of
  28235.                                    TRUE means sound is generated.
  28236.  
  28237.  SV_CURSORRATE                     Specifies the rate at which the cursor
  28238.                                    blinks, in milliseconds. The blink rate
  28239.                                    is the time that the cursor remains
  28240.                                    visible or invisible. Twice this value
  28241.                                    is the time the cursor takes to cycle
  28242.                                    from visibility to invisibility and back.
  28243.  
  28244.  SV_FIRSTSCROLLRATE                Specifies the delay (in milliseconds)
  28245.                                    between clicking and holding down the
  28246.                                    mouse button (when the mouse pointer is
  28247.                                    on a scroll arrow or scroll bar) and the
  28248.                                    beginning of scroll-bar auto-repeat
  28249.                                    activity.
  28250.  
  28251.  SV_SCROLLRATE                     Specifies the delay (in milliseconds)
  28252.                                    between scroll-bar auto-repeat events.
  28253.  
  28254.  SV_ERRORFREQ                      Specifies the frequency (in hertz) of a
  28255.                                    WinAlarm function WA_ERROR sound.
  28256.  
  28257.  SV_NOTEFREQ                       Specifies the frequency (in hertz) of a
  28258.                                    WinAlarm function WA_NOTE sound.
  28259.  
  28260.  SV_WARNINGFREQ                    Specifies the frequency (in hertz) of a
  28261.                                    WinAlarm function WA_WARNING sound.
  28262.  
  28263.  SV_ERRORDURATION                  Specifies the duration (in milliseconds)
  28264.                                    of a WinAlarm function WA_ERROR sound.
  28265.  
  28266.  SV_NOTEDURATION                   Specifies the duration (in milliseconds)
  28267.                                    of a WinAlarm function WA_NOTE sound.
  28268.  
  28269.  SV_WARNINGDURATION                Specifies the duration (in milliseconds)
  28270.                                    of a WinAlarm function WA_WARNING sound.
  28271.  
  28272.  SV_EXTRAKEYBEEP                   Specifies whether beep is turned on for
  28273.                                    extended keys (keys not on an IBM PS/2
  28274.                                    or compatible keyboard).
  28275.  
  28276.  SV_SETLIGHTS                      Specifies whether the system controls
  28277.                                    the keyboard indicator lights.
  28278.  
  28279.  SV_INSERTMODE                     Specifies whether insert mode is on or
  28280.                                    off for entry-field controls.
  28281.  
  28282.  SV_MENUROLLDOWNDELAY              Specifies the delay (in milliseconds)
  28283.                                    for the menu to roll down.
  28284.  
  28285.  SV_MENUROLLUPDELAY                Specifies the delay (in milliseconds)
  28286.                                    for the menu to roll up.
  28287.  
  28288.  SV_ALTMNEMONIC                    Specifies whether the Alt key is allowed
  28289.                                    as a mnemonic.
  28290.  
  28291.  SV_TASKLISTMOUSEACCESS            Specifies whether the Task List can be
  28292.                                    accessed by the right mouse button.
  28293.  
  28294.  
  28295.  
  28296.  For a list of system values that can be queried, see the "Comments" section
  28297.  of the WinQuerySysValue function.
  28298.  
  28299.  lValue  Specifies the value to set the system value to. Durations are in
  28300.  milliseconds. Frequencies are in hertz; valid values are 0x0025 through
  28301.  0x7FFF.
  28302.  
  28303.  
  28304.  Return Value
  28305.  
  28306.  The return value is TRUE if the system value is successfully set. Otherwise,
  28307.  it is FALSE, indicating that an error occurred.
  28308.  
  28309.  
  28310.  See Also
  28311.  
  28312.  WinQuerySysValue
  28313.  
  28314.  
  28315.  Changes
  28316.  
  28317.  The following system values have been added:
  28318.  
  28319.       SV_EXTRAKEYBEEP
  28320.       SV_SETLIGHTS
  28321.       SV_INSERTMODE
  28322.       SV_MENUROLLDOWNDELAY
  28323.       SV_MENUROLLUPDELAY
  28324.       SV_ALTMNEMONIC
  28325.       SV_TASKLISTMOUSEACCESS
  28326.  
  28327.  
  28328.  
  28329.  
  28330.  
  28331.  Corrections
  28332.  
  28333.  Though all system values can be queried, they cannot all be set. The list of
  28334.  system values has been changed to show only those values that can be set.
  28335.  
  28336.  
  28337.  █    WinSetWindowPos
  28338.  ────────────────────────────────────────────────────────────────────────────
  28339.  
  28340.  BOOL WinSetWindowPos  (hwnd, hwndInsertBehind, x, y, cx, cy, fs)
  28341.  
  28342.  HWND  hwnd;                       /*handle of window being set */
  28343.  
  28344.  HWND  hwndInsertBehind;           /*placement-order handle */
  28345.  
  28346.  SHORT  x;                         /*horizontal position */
  28347.  
  28348.  SHORT  y;                         /*vertical position */
  28349.  
  28350.  SHORT  cx;                        /*width */
  28351.  
  28352.  SHORT  cy;                        /*height */
  28353.  
  28354.  USHORT  fs;                       /*window-positioning flags */
  28355.  
  28356.  
  28357.  The WinSetWindowPos function sets the position of a window.
  28358.  
  28359.  
  28360.  Parameters
  28361.  
  28362.  hwnd  Identifies the window being set.
  28363.  
  28364.  hwndInsertBehind  Identifies relative window-placement order. This parameter
  28365.  is ignored if the fs parameter is not set to SWP_ZORDER. If this parameter
  28366.  is HWND_BOTTOM, the hwnd window is placed behind all sibling windows. If it
  28367.  is HWND_TOP, the hwnd window is placed on top of all sibling windows. Other
  28368.  values identify the sibling window behind which the hwnd window is placed.
  28369.  
  28370.  x  Specifies the horizontal position of the hwnd window (in window
  28371.  coordinates relative to the lower-left corner of its parent window). This
  28372.  parameter is ignored if the fs parameter is not set to SWP_MOVE.
  28373.  
  28374.  y  Specifies the vertical position of the hwnd window (in window coordinates
  28375.  relative to the lower-left corner of its parent window). This parameter is
  28376.  ignored if the fs parameter is not set to SWP_MOVE.
  28377.  
  28378.  cx  Specifies the horizontal window size (in device units). This parameter
  28379.  is ignored if the fs parameter is not set to SWP_SIZE.
  28380.  
  28381.  cy  Specifies the vertical window size (in device units). This parameter is
  28382.  ignored if the fs parameter is not set to SWP_SIZE.
  28383.  
  28384.  fs  Identifies the window-positioning options. This parameter can be one or
  28385.  more of the following values:
  28386.  
  28387.  Value                             Meaning
  28388.  ────────────────────────────────────────────────────────────────────────────
  28389.  
  28390.  SWP_ACTIVATE                      The window is activated and the focus to
  28391.                                    be set to the window that lost the focus
  28392.                                    the last time the frame window was
  28393.                                    deactivated. The activated window may
  28394.                                    not become the top window if it owns
  28395.                                    other frame windows.
  28396.  
  28397.  SWP_DEACTIVATE                    Deactivates the window, if it is the
  28398.                                    active window. -
  28399.  
  28400.  SWP_EXTSTATECHANGE                This flag is for application use. It is
  28401.                                    used to pass an additional flag to the
  28402.                                    portion of code that is handling
  28403.                                    messages.
  28404.  
  28405.  SWP_FOCUSACTIVATE                 Specifies that a frame window is
  28406.                                    receiving the focus. This flag is set so
  28407.                                    that an application that is processing
  28408.                                    the WM_ADJUSTWINDOWPOS message can tell
  28409.                                    if the message was sent as the result of
  28410.                                    a focus change.
  28411.  
  28412.  SWP_FOCUSDEACTIVATE               Specifies that a frame window is losing
  28413.                                    the focus. .
  28414.  
  28415.  SWP_HIDE                          Specifies that the window is to be
  28416.                                    hidden when created.
  28417.  
  28418.  SWP_MAXIMIZE                      With SWP_MINIMIZE, causes a window to be
  28419.                                    minimized, maximized, or restored.
  28420.                                    SWP_MAXIMIZE and SWP_MINIMIZE are
  28421.                                    mutually exclusive. If either
  28422.                                    SWP_MINIMIZE or SWP_MAXIMIZE is
  28423.                                    specified, then both SWP_MOVE and
  28424.                                    SWP_SIZE must also be specified.
  28425.                                    WinSetWindowPos and WinSetMultWindowPos
  28426.                                    depend on the previous state of the
  28427.                                    window; these flags cause the
  28428.                                    appropriate state to be toggled, as
  28429.                                    follows: the x, y, cx, and cy parameters
  28430.                                    specify the size and position to which
  28431.                                    the window will be restored if it is
  28432.                                    subsequently restored. This should be
  28433.                                    the normal size of the window.
  28434.  
  28435.  SWP_MINIMIZE                      See SWP_MAXIMIZE.
  28436.  
  28437.  SWP_MOVE                          Changes the window's x,y position.
  28438.  
  28439.  SWP_NOADJUST                      Does not send a WM_ADJUSTWINDOWPOS
  28440.                                    message to the window while processing
  28441.                                    (the window cannot readjust itself).
  28442.  
  28443.  SWP_NOREDRAW                      Does not redraw changes.
  28444.  
  28445.  SWP_RESTORE                       Restores a minimized or maximized window.
  28446.  
  28447.  SWP_SHOW                          Specifies that the window is to be shown
  28448.                                    when created.
  28449.  
  28450.  SWP_SIZE                          Changes the window size.
  28451.  
  28452.  SWP_ZORDER                        Changes the relative window placement.
  28453.  
  28454.  
  28455.  
  28456.  Return Value
  28457.  
  28458.  The return value is TRUE if the function is successful or FALSE if an error
  28459.  occurs.
  28460.  
  28461.  
  28462.  Comments
  28463.  
  28464.  If a window created with the CS_SAVEBITS style is moved, reduced in size, or
  28465.  hidden, the saved screen image is used to redraw the area uncovered when the
  28466.  window size changes, if those bits are still valid.
  28467.  
  28468.  If the CS_SIZEREDRAW style is present, the entire window area is assumed
  28469.  invalid if sized. Otherwise, a WM_CALCVALIDRECTS message is sent to the
  28470.  window to inform the window manager which bits it is possible to preserve.
  28471.  
  28472.  Messages sent from WinSetWindowPos and WinSetMultWindowPos have specific
  28473.  orders within the window positioning process. The process begins with
  28474.  redundancy checks and precalculations on every window for each requested
  28475.  operation. For example, if SWP_SHOW is present but the window is already
  28476.  visible, then SWP_SHOW is turned off. If SWP_SIZE is present and the new
  28477.  size is equal to the previous size, SWP_SIZE is turned off. If the
  28478.  operations will create new results, the information is calculated and
  28479.  stored. For example, if being sized or moved, the new window rectangle is
  28480.  stored for later use. At this point, the WM_ADJUSTWINDOWPOS message is sent
  28481.  to any window that is being sized or moved. Also at this point, the
  28482.  WM_CALCVALIDRECTS message is sent to any window that is being sized and that
  28483.  does not have the CS_SIZEREDRAW window style.
  28484.  
  28485.  When the new window state is calculated, the window-management process
  28486.  begins. Window areas that can be preserved are moved from the old to the new
  28487.  positions, window areas that are invalidated by these operations are
  28488.  calculated and distributed as update regions, and so forth. When this is
  28489.  finished, and before any synchronous-paint windows are repainted, the
  28490.  WM_SIZE message is sent to any windows that have changed size. Next, all the
  28491.  synchronous-paint windows that can be repainted are repainted and the entire
  28492.  process is complete.
  28493.  
  28494.  If a synchronous-paint parent window has a size-sensitive area displayed
  28495.  that includes synchronous-paint child windows, the parent window will
  28496.  reposition those windows when it receives the WM_SIZE message. Their invalid
  28497.  regions will be added to the parent window's invalid region, resulting in
  28498.  one update after the parent window's WM_SIZE message, rather than many
  28499.  independent and subsequently duplicated updates.
  28500.  
  28501.  Certain windows are not positioned precisely to the parameters specified by
  28502.  this function. For example, frame windows without the FCF_NOBYTEALIGN style
  28503.  creation flag are not positioned to any specific screen coordinate.
  28504.  
  28505.  The following messages are sent by this function:
  28506.  
  28507.  Value                             Meaning
  28508.  ────────────────────────────────────────────────────────────────────────────
  28509.  
  28510.  WM_CALCVALIDRECTS                 Sent to determine the area of a window
  28511.                                    that it may be possible to preserve as
  28512.                                    the window is sized.
  28513.  
  28514.  WM_SIZE                           Sent if the size of the window has
  28515.                                    changed, after the change has been
  28516.                                    effected.
  28517.  
  28518.  WM_MOVE                           Sent when a window with CS_MOVENOTIFY
  28519.                                    class style moves its absolute position.
  28520.  
  28521.  WM_ACTIVATE                       Sent if a different window becomes the
  28522.                                    active window. For more information, see
  28523.                                    the WinSetActiveWindow function.
  28524.  
  28525.  WM_ADJUSTWINDOWPOS                Sent if SWP_NOADJUST is not specified.
  28526.                                    The message's mp1 parameter points to an
  28527.                                    SWP structure that has been filled in by
  28528.                                    the WinSetWindowPos function with the
  28529.                                    proposed move/size data. The window can
  28530.                                    adjust this new position by changing the
  28531.                                    contents of the SWP structure.
  28532.  
  28533.  
  28534.  
  28535.  Example
  28536.  
  28537.  This example gets the dimensions of the desktop window, and calls
  28538.  WinSetWindowPos to place the application's frame window in the upper left
  28539.  corner. By positioning the window relative to the desktop window, the window
  28540.  position is device-independent; it will work on any display adapter no
  28541.  matter what the vertical and horizontal resolution is.
  28542.  
  28543.  RECTL rcl;
  28544.  
  28545.  WinQueryWindowRect(HWND_DESKTOP, &rcl);
  28546.  WinSetWindowPos(hwndFrame, HWND_TOP,
  28547.      rcl.xLeft,                                      /* x pos  */
  28548.      rcl.yTop - 60,                                  /* y pos  */
  28549.      140,                                            /* x size */
  28550.      60,                                             /* y size */
  28551.      SWP_ACTIVATE | SWP_MOVE | SWP_SIZE | SWP_SHOW); /* flags  */
  28552.  
  28553.  
  28554.  
  28555.  
  28556.  
  28557.  See Also
  28558.  
  28559.  WinSetActiveWindow, WinSetMultWindowPos
  28560.  
  28561.  
  28562.  Corrections
  28563.  
  28564.  Certain windows are not positioned precisely to the parameters specified by
  28565.  this function. For example, frame windows without a style creation flag of
  28566.  FCF_NOBYTEALIGN are not positioned to any specific screen coordinate.
  28567.  
  28568.  
  28569.  █    WinSwitchToProgram
  28570.  ────────────────────────────────────────────────────────────────────────────
  28571.  
  28572.  USHORT WinSwitchToProgram  (hSwitch)
  28573.  
  28574.  HSWITCH  hSwitch;                 /*handle of application to activate */
  28575.  
  28576.  
  28577.  The WinSwitchToProgram function makes an application the active application.
  28578.  The function succeeds only if the calling application is currently the
  28579.  active application (the application with the active window).
  28580.  
  28581.  
  28582.  Parameters
  28583.  
  28584.  hSwitch  Identifies the application to make active.
  28585.  
  28586.  
  28587.  Return Value
  28588.  
  28589.  The return value is zero if the function is successful. Otherwise, it is an
  28590.  error value, which may be the following:
  28591.  
  28592.      PMERR_INVALID_SWITCH_HANDLE
  28593.  
  28594.  
  28595.  
  28596.  
  28597.  
  28598.  See Also
  28599.  
  28600.  WinInstStartApp
  28601.  
  28602.  
  28603.  █    WinTerminateApp
  28604.  ────────────────────────────────────────────────────────────────────────────
  28605.  
  28606.  BOOL WinTerminateApp  (happ)
  28607.  
  28608.  HAPP  happ;                       /*application handle */
  28609.  
  28610.  
  28611.  The WinTerminateApp function terminates an application previously started
  28612.  with the WinInstStartApp function.
  28613.  
  28614.  
  28615.  Parameters
  28616.  
  28617.  happ  Identifies the application to terminate.
  28618.  
  28619.  
  28620.  Return Value
  28621.  
  28622.  The return value is TRUE if the application is terminated successfully or
  28623.  NULL if an error occurs.
  28624.  
  28625.  
  28626.  Errors
  28627.  
  28628.  Use the WinGetLastError function to retrieve the error value, which may be
  28629.  one of the following:
  28630.  
  28631.       PMERR_INVALID_HAPP
  28632.       PMERR_CANNOT_STOP
  28633.  
  28634.  
  28635.  
  28636.  
  28637.  
  28638.  Comments
  28639.  
  28640.  The application to terminate must have been started using the
  28641.  WinInstStartApp function with the SAF_STARTCHILDAPP option specified.
  28642.  
  28643.  If the specified application does not stop, this function returns TRUE. To
  28644.  ensure that the application has terminated, the application calling
  28645.  WinTerminateApp must wait for the appropriate message to be posted to the
  28646.  window specified in the WinInstStartApp function.
  28647.  
  28648.  
  28649.  See Also
  28650.  
  28651.  WinInstStartApp
  28652.  
  28653.  
  28654.  █    WinWindowFromID
  28655.  ────────────────────────────────────────────────────────────────────────────
  28656.  
  28657.  HWND WinWindowFromID  (hwndParent, id)
  28658.  
  28659.  HWND  hwndParent;                 /*parent-window handle */
  28660.  
  28661.  USHORT  id;                       /*window identifier */
  28662.  
  28663.  
  28664.  The WinWindowFromID function returns the first child window that has the
  28665.  specified identifier of the specified parent window.
  28666.  
  28667.  
  28668.  Parameters
  28669.  
  28670.  hwndParent  Identifies the parent window.
  28671.  
  28672.  id  Identifies the window.
  28673.  
  28674.  
  28675.  Return Value
  28676.  
  28677.  The return value is a window handle. If no child window exists with
  28678.  identifier id the return value is NULL.
  28679.  
  28680.  
  28681.  Comments
  28682.  
  28683.  To obtain the window handle for an item within a dialog box, the hwndParent
  28684.  parameter is set to the dialog-box window's handle and the id parameter is
  28685.  set to the identifier of the item in the dialog template.
  28686.  
  28687.  To obtain the window handle for a frame control, the hwndParent parameter is
  28688.  set to the frame window's handle and the id parameter is set to one of the
  28689.  FID constants, indicating which frame control you want a handle of.
  28690.  
  28691.  The following list contains the frame control identifiers. Note that you
  28692.  must also define the INCL_WINFRAMEMGR constant before including pmwin.h.
  28693.  
  28694.  Value                             Meaning
  28695.  ────────────────────────────────────────────────────────────────────────────
  28696.  
  28697.  FID_CLIENT                        Identifies the client window.
  28698.  
  28699.  FID_HORZSCROLL                    Identifies the horizontal scroll bar.
  28700.  
  28701.  FID_MENU                          Identifies the application menu.
  28702.  
  28703.  FID_MINMAX                        Identifies the minimize/maximize box.
  28704.  
  28705.  FID_SYSMENU                       Identifies the system menu.
  28706.  
  28707.  FID_TITLEBAR                      Identifies the title bar.
  28708.  
  28709.  FID_VERTSCROLL                    Identifies the vertical scroll bar.
  28710.  
  28711.  
  28712.  
  28713.  Example
  28714.  
  28715.  This example calls WinWindowFromID to get the window handle of the system
  28716.  menu and calls WinSendMsg to send a message to disable the Close menu item.
  28717.  
  28718.  #define INCL_WINMESSAGEMGR   /* includes message manager functions */
  28719.  #define INCL_WINFRAMEMGR     /* includes FID_ constants            */
  28720.  #include <os2.h>
  28721.  
  28722.  HWND hwndSysMenu;
  28723.  
  28724.  hwndSysMenu = WinWindowFromID(hwndDlg, FID_SYSMENU);
  28725.  WinSendMsg(hwndSysMenu, MM_SETITEMATTR,
  28726.      MPFROM2SHORT(SC_CLOSE, TRUE),
  28727.      MPFROM2SHORT(MIA_DISABLED, MIA_DISABLED));
  28728.  
  28729.  
  28730.  
  28731.  
  28732.  
  28733.  See Also
  28734.  
  28735.  WinMultWindowFromIDs, WinWindowFromPoint
  28736.  
  28737.  
  28738.  Corrections
  28739.  
  28740.  The list of FID constants incorrectly identified FID_MENU as referring to
  28741.  the system menu. It actually refers to the application menu.
  28742.  
  28743.  
  28744.  █    WinWindowFromPoint
  28745.  ────────────────────────────────────────────────────────────────────────────
  28746.  
  28747.  HWND WinWindowFromPoint  (hwnd, pptl, fChildren, fLock)
  28748.  
  28749.  HWND  hwnd;                       /*handle of the window */
  28750.  
  28751.  PPOINTL  pptl;                    /*address of structure with the point */
  28752.  
  28753.  BOOL  fChildren;                  /*scope flag */
  28754.  
  28755.  BOOL  fLock;                      /*lock/unlock flag */
  28756.  
  28757.  
  28758.  The WinWindowFromPoint function finds the window that is below a specified
  28759.  point and that is a descendant of a specified window. This function checks
  28760.  only the descendants of the specified window.
  28761.  
  28762.  
  28763.  Parameters
  28764.  
  28765.  hwnd  Identifies the window whose child windows are tested.
  28766.  
  28767.  pptl  Points to a POINTL structure that contains the point to test,
  28768.  specified in window coordinates relative to the hwnd parameter. The POINTL
  28769.  structure has the following form:
  28770.  
  28771.  typedef struct _POINTL  {
  28772.      LONG  x;
  28773.      LONG  y;
  28774.  } POINTL;
  28775.  
  28776.  
  28777.  
  28778.  
  28779.  For a full description, see Chapter 4, "Types, Macros, Structures."
  28780.  
  28781.  fChildren  Specifies which child windows to test. If fChildren is TRUE, the
  28782.  function tests all the descendants of hwnd, including child windows of child
  28783.  windows. If fChildren is FALSE, the function tests only the immediate child
  28784.  windows of hwnd.
  28785.  
  28786.  fLock  This parameter is ignored by MS OS/2 versions 1.2 and later.
  28787.  
  28788.  
  28789.  Return Value
  28790.  
  28791.  If fChildren is FALSE, the return value is hwnd, a child of hwnd, or NULL.
  28792.  If fChildren is TRUE, the return value is the topmost window if that window
  28793.  is hwnd or a child of hwnd─unless another window of CS_HITTEST type is
  28794.  found, in which case the window returned may not be the topmost window.
  28795.  
  28796.  
  28797.  See Also
  28798.  
  28799.  WinWindowFromID
  28800.  
  28801.  
  28802.  Changes
  28803.  
  28804.  The fLock parameter is ignored by MS OS/2 versions 1.2 and later.
  28805.  
  28806.  
  28807.  █    WinWriteProfileData
  28808.  ────────────────────────────────────────────────────────────────────────────
  28809.  
  28810.  
  28811.  
  28812.  The WinWriteProfileData function provides compatibility with MS OS/2
  28813.  versions 1.1 and earlier. Applications intended exclusively for MS OS/2
  28814.  versions 1.2 and later should use the PrfWriteProfileData function.
  28815.  
  28816.  
  28817.  
  28818.  
  28819.  █    WinWriteProfileString
  28820.  ────────────────────────────────────────────────────────────────────────────
  28821.  
  28822.  
  28823.  
  28824.  The WinWriteProfileString function provides compatibility with MS OS/2
  28825.  versions 1.1 and earlier. Applications intended exclusively for MS OS/2
  28826.  versions 1.2 and later should use the PrfWriteProfileString function.
  28827.  
  28828.  
  28829.  
  28830.  
  28831.  █    WM_ADJUSTWINDOWPOS
  28832.  ────────────────────────────────────────────────────────────────────────────
  28833.  
  28834.  
  28835.  WM_ADJUSTWINDOWPOS
  28836.  pswp = (PSWP) PVOIDFROMMP(mp1);    /* pointer to SWP structure */
  28837.  
  28838.  
  28839.  The WM_ADJUSTWINDOWPOS message is sent when a window is about to be moved or
  28840.  sized. It gives the window an opportunity to adjust the new size and
  28841.  position before the window is actually moved and sized.
  28842.  
  28843.  
  28844.  Parameters
  28845.  
  28846.  pswp  Low and high words of mp1. Points to an SWP structure that contains
  28847.  the new window size and position information. The SWP structure has the
  28848.  following form:
  28849.  
  28850.  typedef struct _SWP {
  28851.      USHORT fs;
  28852.      SHORT  cy;
  28853.      SHORT  cx;
  28854.      SHORT  y;
  28855.      SHORT  x;
  28856.      HWND   hwndInsertBehind;
  28857.      HWND   hwnd;
  28858.  } SWP;
  28859.  
  28860.  
  28861.  
  28862.  
  28863.  For a full description, see Chapter 4, "Types, Macros, Structures."
  28864.  
  28865.  
  28866.  Return Value
  28867.  
  28868.  An application should return FALSE if it does not change the SWP structure.
  28869.  Otherwise, it should return on of the following values:
  28870.  
  28871.  Value                             Meaning
  28872.  ────────────────────────────────────────────────────────────────────────────
  28873.  
  28874.  AWP_MINIMIZED                     The window was minimized.
  28875.  
  28876.  AWP_MAXIMIZED                     The window was maximized.
  28877.  
  28878.  AWP_RESTORED                      The window was restored.
  28879.  
  28880.  AWP_ACTIVATE                      The window was activated.
  28881.  
  28882.  AWP_DEACTIVATE                    The window was deactivated.
  28883.  
  28884.  
  28885.  
  28886.  See Also
  28887.  
  28888.  WinCreateWindow, WM_CALCVALIDRECTS, WM_WINDOWPOSCHANGED
  28889.  
  28890.  
  28891.  Changes
  28892.  
  28893.  An application should return FALSE if it does not change the SWP structure.
  28894.  Otherwise, it should return on of the following values:
  28895.  
  28896.  Value                             Meaning
  28897.  ────────────────────────────────────────────────────────────────────────────
  28898.  
  28899.  AWP_MINIMIZED                     The window was minimized.
  28900.  
  28901.  AWP_MAXIMIZED                     The window was maximized.
  28902.  
  28903.  AWP_RESTORED                      The window was restored.
  28904.  
  28905.  AWP_ACTIVATE                      The window was activated.
  28906.  
  28907.  AWP_DEACTIVATE                    The window was deactivated.
  28908.  
  28909.  
  28910.  
  28911.  █    WM_APPTERMINATENOTIFY
  28912.  ────────────────────────────────────────────────────────────────────────────
  28913.  
  28914.  
  28915.  WM_APPTERMINATENOTIFY
  28916.  mp1 = MPFROMLONG((HAPP) happ);            /* application handle */
  28917.  mp2 = MPFROMSHORT((USHORT) usRetCode);    /* return code        */
  28918.  
  28919.  
  28920.  The WM_APPTERMINATENOTIFY message is sent when a child application started
  28921.  by the WinInstStartApp function terminates.
  28922.  
  28923.  
  28924.  Parameters
  28925.  
  28926.  happ  Low word of mp1. Identifies the application returned by the
  28927.  WinInstStartApp function.
  28928.  
  28929.  usRetCode  Low word of mp2. Specifies the return code from the application
  28930.  that has terminated.
  28931.  
  28932.  
  28933.  Return Value
  28934.  
  28935.  An application should return zero if it processes this message.
  28936.  
  28937.  
  28938.  See Also
  28939.  
  28940.  WinInstStartApp, WinTerminateApp
  28941.  
  28942.  
  28943.  █    WM_CALCFRAMERECT
  28944.  ────────────────────────────────────────────────────────────────────────────
  28945.  
  28946.  
  28947.  WM_CALCFRAMERECT
  28948.  prclFrame = (PRECTL) PVOIDFROMMP(mp1); /* pointer to RECTL structure */
  28949.  fClient = (BOOL) SHORT1FROMMP(mp2);    /* client-indicator flag      */
  28950.  
  28951.  
  28952.  The WM_CALCFRAMERECT message is sent to a frame window when the
  28953.  WinCalcFrameRect function is called. The default window procedure calculates
  28954.  a client rectangle from a frame rectangle or calculates a frame rectangle
  28955.  from a client rectangle.
  28956.  
  28957.  
  28958.  Parameters
  28959.  
  28960.  prcl  Low word of mp1. Points to the RECTL structure that contains the
  28961.  coordinates of the window. If the fClient parameter is TRUE, this structure
  28962.  contains the coordinates of the frame window, and on return, it contains the
  28963.  coordinates of a client window. If the fClient parameter is FALSE, this
  28964.  structure contains the coordinates of the client window, and on return, it
  28965.  contains the coordinates of a frame window.
  28966.  
  28967.  The RECTL structure has the following form:
  28968.  
  28969.  typedef struct _RECTL {
  28970.      LONG  xLeft;
  28971.      LONG  yBottom;
  28972.      LONG  xRight;
  28973.      LONG  yTop;
  28974.  } RECTL;
  28975.  
  28976.  
  28977.  
  28978.  
  28979.  For a full description, see Chapter 4, "Types, Macros, Structures."
  28980.  
  28981.  fClient  Low word of mp2. Specifies whether the window to calculate is a
  28982.  client window or a frame window. If this value is TRUE, a client window is
  28983.  calculated. If this value is FALSE, a frame window is calculated.
  28984.  
  28985.  
  28986.  Return Value
  28987.  
  28988.  If an application processes this message, it should return TRUE if
  28989.  successful or FALSE if an error occurs or the calculated rectangle is empty.
  28990.  
  28991.  
  28992.  
  28993.  See Also
  28994.  
  28995.  WinCalcFrameRect
  28996.  
  28997.  
  28998.  █    WM_CALCVALIDRECTS
  28999.  ────────────────────────────────────────────────────────────────────────────
  29000.  
  29001.  
  29002.  WM_CALCVALIDRECTS
  29003.  parclWindow = (PRECTL) PVOIDFROMMP(mp1);   /* source rectangle   */
  29004.  pswpDest = (PSWP) PVOIDFROMMP(mp2);        /* destination window */
  29005.  
  29006.  
  29007.  The WM_CALCVALIDRECTS message is sent when a window is about to be resized.
  29008.  This allows the application to specify the coordinates of a rectangle that
  29009.  will be preserved and to designate where this rectangle will be moved in the
  29010.  resized window. Areas outside this rectangle will be redrawn.
  29011.  
  29012.  
  29013.  Parameters
  29014.  
  29015.  parclWindow  Low and high words of mp1. Points to an array of two RECTL
  29016.  structures that contain the dimensions of the window before and after
  29017.  resizing. The first RECTL structure contains the source rectangle; the
  29018.  second RECTL structure contains the destination rectangle. The coordinates
  29019.  of the rectangles are relative to the parent window of the window. The RECTL
  29020.  structure has the following form:
  29021.  
  29022.  typedef struct _RECTL {
  29023.      LONG  xLeft;
  29024.      LONG  yBottom;
  29025.      LONG  xRight;
  29026.      LONG  yTop;
  29027.  } RECTL;
  29028.  
  29029.  
  29030.  
  29031.  
  29032.  For a full description, see Chapter 4, "Types, Macros, Structures."
  29033.  
  29034.  pswpDest  Low and high words of mp2. Points to the SWP structure that
  29035.  contains information about the window after it is resized. The SWP structure
  29036.  has the following form:
  29037.  
  29038.  typedef struct _SWP {
  29039.      USHORT fs;
  29040.      SHORT  cy;
  29041.      SHORT  cx;
  29042.      SHORT  y;
  29043.      SHORT  x;
  29044.      HWND   hwndInsertBehind;
  29045.      HWND   hwnd;
  29046.  } SWP;
  29047.  
  29048.  
  29049.  
  29050.  
  29051.  For a full description, see Chapter 4, "Types, Macros, Structures."
  29052.  
  29053.  
  29054.  Return Value
  29055.  
  29056.  If an application processes this message, it can return zero to indicate it
  29057.  has changed the rectangle itself, CVR_REDRAW if the entire window is to be
  29058.  redrawn, or a combination of the following values:
  29059.  
  29060.  Value                             Meaning
  29061.  ────────────────────────────────────────────────────────────────────────────
  29062.  
  29063.  CVR_ALIGNBOTTOM                   Align with the bottom edge of the window.
  29064.  
  29065.  CVR_ALIGNLEFT                     Align with the left edge of the window.
  29066.  
  29067.  CVR_ALIGNRIGHT                    Align with the right edge of the window.
  29068.  
  29069.  CVR_ALIGNTOP                      Align with the top edge of the window.
  29070.  
  29071.  
  29072.  
  29073.  Comments
  29074.  
  29075.  The WM_CALCVALIDRECTS message is not sent if a window has the CS_SIZEREDRAW
  29076.  style because such windows are always completely redrawn when resized.
  29077.  
  29078.  
  29079.  See Also
  29080.  
  29081.  WM_ADJUSTWINDOWPOS
  29082.  
  29083.  
  29084.  Corrections
  29085.  
  29086.  The first parameter points to an array of two RECTL structures. The first
  29087.  structure is the source rectangle; the second structure is the destination
  29088.  rectangle.
  29089.  
  29090.  The second parameter points to an SWP structure, not to a RECTL structure.
  29091.  
  29092.  The CVR_REDRAW constant was incorrectly spelled CV_REDRAW.
  29093.  
  29094.  
  29095.  █    WM_CHAR
  29096.  ────────────────────────────────────────────────────────────────────────────
  29097.  
  29098.  
  29099.  WM_CHAR
  29100.  fsKeyFlags = (USHORT) SHORT1FROMMP(mp1);    /* key flags             */
  29101.  uchRepeat = (UCHAR) CHAR3FROMMP(mp1);       /* repeat count          */
  29102.  uchScanCode = (UCHAR) CHAR4FROMMP(mp1);     /* scan code             */
  29103.  usChr1 = (UCHAR) CHAR1FROMMP(mp2);          /* character             */
  29104.  usChr2 = (UCHAR) CHAR2FROMMP(mp2);          /* 2nd byte of character */
  29105.  usVKey = (USHORT) SHORT2FROMMP(mp2);        /* virtual key           */
  29106.  
  29107.  
  29108.  The WM_CHAR message is sent whenever the user presses a key. This message is
  29109.  placed in the queue associated with the window that has the focus.
  29110.  
  29111.  
  29112.  Parameters
  29113.  
  29114.  fsKeyFlags  Low word of mp1. Specifies the keyboard control codes. It can be
  29115.  one or more of the following values:
  29116.  
  29117.  Value                             Meaning
  29118.  ────────────────────────────────────────────────────────────────────────────
  29119.  
  29120.  KC_CHAR                           The usChr parameter value is valid.
  29121.  
  29122.  KC_SCANCODE                       The uchScanCode parameter value is
  29123.                                    valid; otherwise, uchScanCode contains
  29124.                                    zero.
  29125.  
  29126.  KC_VIRTUALKEY                     The usVKey parameter value is valid;
  29127.                                    otherwise, usVKey contains zero.
  29128.  
  29129.  KC_KEYUP                          The event was a key-up transition;
  29130.                                    otherwise, it was a key-down transition.
  29131.  
  29132.  KC_PREVDOWN                       The key was previously down; otherwise,
  29133.                                    it was previously up.
  29134.  
  29135.  KC_DEADKEY                        The character code is a dead key. The
  29136.                                    application must display the glyph for
  29137.                                    the dead key without advancing the
  29138.                                    cursor.
  29139.  
  29140.  KC_COMPOSITE                      The character code was formed by
  29141.                                    combining the current key with the
  29142.                                    previous dead key.
  29143.  
  29144.  KC_INVALIDCOMP                    The character code was not a valid
  29145.                                    combination with the preceding dead key.
  29146.                                    The application must advance the cursor
  29147.                                    past the dead-key glyph and then, if the
  29148.                                    current character is not a space, it
  29149.                                    must beep the speaker and display the
  29150.                                    new character code.
  29151.  
  29152.  KC_LONEKEY                        This flag is set if the key was pressed
  29153.                                    and released without any other keys
  29154.                                    being pressed or released during the
  29155.                                    time the key was pressed and released.
  29156.  
  29157.  KC_SHIFT                          The shift state was active when the key
  29158.                                    was pressed or released.
  29159.  
  29160.  KC_ALT                            The ALT state was active when the key
  29161.                                    was pressed or released.
  29162.  
  29163.  KC_CTRL                           The CONTROL state was active when the
  29164.                                    key was pressed or released.
  29165.  
  29166.  
  29167.  
  29168.  uchRepeat  Low byte of high word of mp1. Specifies the repeat count of the
  29169.  key.
  29170.  
  29171.  uchScanCode  High byte of high word of mp1. Specifies the character scan
  29172.  code of the character.
  29173.  
  29174.  usChr1  First byte of the low word of mp2. Specifies the ASCII character.
  29175.  
  29176.  usChr2  Second byte of the low word of mp2, for double-byte characters only.
  29177.  Specifies second byte of the character, or is zero for standard ASCII.
  29178.  
  29179.  usVKey  High word of mp2. Specifies the virtual-key code.
  29180.  
  29181.  
  29182.  Comments
  29183.  
  29184.  Generally, all WM_CHAR messages generated from actual user input have the
  29185.  KC_SCANCODE code set. However, if the message has been generated by an
  29186.  application that has issued the WinSetHook function to filter keystrokes, or
  29187.  if it was posted to the application queue, this code may not be set.
  29188.  
  29189.  The CHARMSG macro can be used to access the WM_CHAR message parameters. This
  29190.  macro defines a CHARMSG structure pointer that has the following form:
  29191.  
  29192.  struct _CHARMSG {
  29193.      USHORT chr;             /* mp2 */
  29194.      USHORT vkey;
  29195.      USHORT fs;              /* mp1 */
  29196.      UCHAR  cRepeat;
  29197.      UCHAR  scancode;
  29198.  };
  29199.  
  29200.  
  29201.  
  29202.  
  29203.  When the character returned is a double-byte character, then the second byte
  29204.  of mp2 contains the second byte of the character. For standard ASCII, the
  29205.  second byte is zero.
  29206.  
  29207.  
  29208.  Example
  29209.  
  29210.  This example uses the CHARMSG macro to process a WM_CHAR message. It first
  29211.  uses the macro to determine if a key was released. It then uses the macro to
  29212.  generate a switch statement based on the character received.
  29213.  
  29214.  MRESULT EXPENTRY GenericWndProc(hwnd, usMessage, mp1, mp2)
  29215.  HWND   hwnd;
  29216.  USHORT usMessage;
  29217.  MPARAM mp1;
  29218.  MPARAM mp2;
  29219.  {
  29220.  
  29221.      switch (usMessage) {
  29222.      case WM_CHAR:
  29223.          if (CHARMSG(&usMessage)->fs & KC_KEYUP) {
  29224.              switch (CHARMSG(&usMessage)->chr) {
  29225.  
  29226.  
  29227.  
  29228.  
  29229.  
  29230.  Return Value
  29231.  
  29232.  An application should return TRUE if it processes the message; otherwise it
  29233.  should return FALSE.
  29234.  
  29235.  
  29236.  See Also
  29237.  
  29238.  WinSetHook, WM_NULL, WM_TRANSLATEACCEL, WM_VIOCHAR
  29239.  
  29240.  
  29241.  Changes
  29242.  
  29243.  For double-byte character sets, the second parameter (mp2) of WM_CHAR
  29244.  contains both bytes of the double-byte character.
  29245.  
  29246.  
  29247.  █    WM_CLOSE
  29248.  ────────────────────────────────────────────────────────────────────────────
  29249.  
  29250.  
  29251.  WM_CLOSE
  29252.  
  29253.  
  29254.  The WM_CLOSE message is sent as a signal that the window or its application
  29255.  should terminate. This message allows the window to control the termination
  29256.  process.
  29257.  
  29258.  
  29259.  Parameters
  29260.  
  29261.  This message does not use any parameters.
  29262.  
  29263.  
  29264.  Return Value
  29265.  
  29266.  An application should return zero if it processes this message.
  29267.  
  29268.  
  29269.  Comments
  29270.  
  29271.  If WM_CLOSE is passed to the WinDefDlgProc function, the function calls the
  29272.  WinDismissDlg function and passes the DID_CANCEL result code to it.
  29273.  
  29274.  
  29275.  Example
  29276.  
  29277.  In the following example, the fChanges variable is checked. If it is TRUE,
  29278.  the user is asked if he or she wants to exit without saving any changes. If
  29279.  the user responds by choosing the No button, then zero is returned and the
  29280.  application does not exit. If the user responds by choosing the Yes button,
  29281.  then a WM_QUIT message is posted so that the application will terminate.
  29282.  
  29283.  case WM_CLOSE:
  29284.      if (fChanges) {
  29285.          if (WinMessageBox(HWND_DESKTOP, hwndClient,
  29286.                  "Do you want to exit without saving your changes?",
  29287.                  "", 0, MB_NOICON | MB_YESNO) == MBID_NO)
  29288.              return (0L);
  29289.      }
  29290.      WinPostMsg(hwnd, WM_QUIT, 0L, 0L);
  29291.      return (0L);
  29292.  
  29293.  
  29294.  
  29295.  
  29296.  
  29297.  See Also
  29298.  
  29299.  WinDefWindowProc, WinMessageBox, WinPostMsg, WM_QUIT
  29300.  
  29301.  
  29302.  Changes
  29303.  
  29304.  If a dialog window has a system menu, selecting the "Close" menu item calls
  29305.  the WinDismissDlg function, passing the DID_CANCEL result code. Previous
  29306.  versions of MS OS/2 closed the application, rather than only the dialog box.
  29307.  
  29308.  
  29309.  
  29310.  █    WM_DRAWITEM
  29311.  ────────────────────────────────────────────────────────────────────────────
  29312.  
  29313.  
  29314.  WM_DRAWITEM
  29315.  id = (USHORT) SHORT1FROMMP(mp1);        /* window ID             */
  29316.  poi = (POWNERITEM) PVOIDFROMMP(mp2);    /* pointer to OWNERITEM  */
  29317.  
  29318.  
  29319.  The WM_DRAWITEM message is sent to the owner of a list box when an item in
  29320.  an owner-drawn list needs to be drawn or highlighted. The list box must have
  29321.  the LS_OWNERDRAW style. The WM_DRAWITEM message is also sent to the owner of
  29322.  a menu when an item in the owner-drawn menu needs to be drawn or
  29323.  highlighted. The menu must have the MIS_OWNERDRAW style.
  29324.  
  29325.  
  29326.  Parameters
  29327.  
  29328.  id  Low word of mp1. Identifies the window of the list-box or menu control
  29329.  sending this message.
  29330.  
  29331.  poi  Low and high words of mp2. Points to an OWNERITEM structure. The
  29332.  OWNERITEM structure has the following form:
  29333.  
  29334.  typedef struct _OWNERITEM {
  29335.      HWND    hwnd;
  29336.      HPS     hps;
  29337.      USHORT  fsState;
  29338.      USHORT  fsAttribute;
  29339.      USHORT  fsStateOld;
  29340.      USHORT  fsAttributeOld;
  29341.      RECTL   rclItem;
  29342.      SHORT   idItem;
  29343.      ULONG   hItem;
  29344.  } OWNERITEM;
  29345.  
  29346.  
  29347.  
  29348.  
  29349.  For a full description, see Chapter 4, "Types, Macros, Structures."
  29350.  
  29351.  
  29352.  Return Value
  29353.  
  29354.  The application should return TRUE if it draws the list-box item; it should
  29355.  return FALSE if the list box should draw the item. If the WM_DRAWITEM
  29356.  message is sent to a menu, the return value is ignored.
  29357.  
  29358.  
  29359.  Comments
  29360.  
  29361.  When an item is to be drawn, the fsState field and the fsStateOld field of
  29362.  the OWNERITEM structure will be equal. The application should draw the item
  29363.  and return TRUE, or it should return FALSE to let the list box draw the
  29364.  item. The list box can draw only text items, so the application must handle
  29365.  the drawing of other types of objects.
  29366.  
  29367.  When an item is to be highlighted, the fsState field is TRUE and the
  29368.  fsStateOld field is FALSE. In this case, the application should carry out
  29369.  the highlighting and set fsState and fsStateOld equal to FALSE before
  29370.  returning TRUE, or it should return FALSE so the list box can perform
  29371.  default highlighting of the item.
  29372.  
  29373.  When highlighting is to be removed from an item, the fsState field is FALSE
  29374.  and the fsStateOld field is TRUE. An application can remove the
  29375.  highlighting, set the fsState and fsStateOld equal to FALSE and return TRUE,
  29376.  or it can return FALSE to let the list box remove the highlighting.
  29377.  
  29378.  
  29379.  See Also
  29380.  
  29381.  LM_QUERYITEMTEXT
  29382.  
  29383.  
  29384.  Corrections
  29385.  
  29386.  The application should return TRUE if it draws the list-box item; it should
  29387.  return FALSE if the list box should draw the item. If the WM_DRAWITEM
  29388.  message is sent to a menu, the return value is ignored.
  29389.  
  29390.  
  29391.  █    WM_FORMATFRAME
  29392.  ────────────────────────────────────────────────────────────────────────────
  29393.  
  29394.  
  29395.  WM_FORMATFRAME
  29396.  paswp = (paswp) PVOIDFROMMP(mp1);    /* pointer to SWP array       */
  29397.  prcl = (PRECTL) PVOIDFROMMP(mp2);    /* pointer to RECTL structure */
  29398.  
  29399.  
  29400.  The WM_FORMATFRAME message is sent to a frame window to calculate the sizes
  29401.  and positions of the frame controls and the client window. The frame-window
  29402.  procedure sends the message to its client window and, if the client window
  29403.  returns TRUE (indicating that it processed the message), no further action
  29404.  occurs. Otherwise, the frame window calls the WinFormatFrame function.
  29405.  
  29406.  
  29407.  Parameters
  29408.  
  29409.  paswp  Low and high words of mp1. Points to an array of SWP structures. The
  29410.  array elements are filled in the order of the FID values of the frame
  29411.  controls, with the FID_CLIENT window always the last element in the array.
  29412.  The SWP structure has the following form:
  29413.  
  29414.  typedef struct _SWP {
  29415.      USHORT fs;
  29416.      SHORT  cy;
  29417.      SHORT  cx;
  29418.      SHORT  y;
  29419.      SHORT  x;
  29420.      HWND   hwndInsertBehind;
  29421.      HWND   hwnd;
  29422.  } SWP;
  29423.  
  29424.  
  29425.  
  29426.  
  29427.  For a full description, See Chapter 4, "Types, Macros, Structures."
  29428.  
  29429.  prcl  Low and high words of mp2. Points to a RECTL structure that contains
  29430.  the rectangle within which the frame controls are formatted. The RECTL
  29431.  structure has the following form:
  29432.  
  29433.  typedef struct _RECTL {
  29434.      LONG  xLeft;
  29435.      LONG  yBottom;
  29436.      LONG  xRight;
  29437.      LONG  yTop;
  29438.  } RECTL;
  29439.  
  29440.  
  29441.  
  29442.  
  29443.  For a full description, see Chapter 4, "Types, Macros, Structures."
  29444.  
  29445.  
  29446.  Return Value
  29447.  
  29448.  An application should return TRUE if it processes this message.
  29449.  
  29450.  
  29451.  Comments
  29452.  
  29453.  Note that the paswp parameter points to memory allocated according to the
  29454.  value returned by the WM_QUERYFRAMECTLCOUNT message. The application must
  29455.  not write beyond this area.
  29456.  
  29457.  
  29458.  See Also
  29459.  
  29460.  WinFormatFrame
  29461.  
  29462.  
  29463.  Corrections
  29464.  
  29465.  The parameters were reversed. The first parameter is the array of SWP
  29466.  structures; the second parameter is a pointer to a RECTL structure.
  29467.  
  29468.  
  29469.  █    WM_MEASUREITEM
  29470.  ────────────────────────────────────────────────────────────────────────────
  29471.  
  29472.  
  29473.  WM_MEASUREITEM
  29474.  id = SHORT1FROMMP(mp1);                 /* list-box identifier  */
  29475.  poi = (POWNERITEM) PVOIDFROMMP(mp2);    /* pointer to OWNERITEM */
  29476.  
  29477.  
  29478.  The WM_MEASUREITEM message is sent to calculate the height of each item in a
  29479.  window. It is normally sent to list boxes and menus. All items are the same
  29480.  height in a list box or menu.
  29481.  
  29482.  
  29483.  Parameters
  29484.  
  29485.  id  Low word of mp1. Specifies the window.
  29486.  
  29487.  poi  Low and high words of mp2. When this message is sent to a menu window,
  29488.  this parameter points to an OWNERITEM structure. Otherwise, this parameter
  29489.  is not used. The OWNERITEM structure has the following form:
  29490.  
  29491.  typedef struct _OWNERITEM {
  29492.      HWND    hwnd;
  29493.      HPS     hps;
  29494.      USHORT  fsState;
  29495.      USHORT  fsAttribute;
  29496.      USHORT  fsStateOld;
  29497.      USHORT  fsAttributeOld;
  29498.      RECTL   rclItem;
  29499.      SHORT   idItem;
  29500.      ULONG   hItem;
  29501.  } OWNERITEM;
  29502.  
  29503.  
  29504.  
  29505.  
  29506.  For a full description, see Chapter 4, "Types, Macros, Structures."
  29507.  
  29508.  
  29509.  Return Value
  29510.  
  29511.  If this message is processed by a list box, the low word of the return value
  29512.  contains the height of the list-box item. If the style LS_HORZSCROLL is set,
  29513.  the high word contains the length of the list-box item; otherwise, the high
  29514.  word must be set to zero.
  29515.  
  29516.  If this message is processed by a menu, the return value is ignored. The
  29517.  width and height are returned by placing their dimensions in the OWNERITEM
  29518.  structure passed in the poi parameter.
  29519.  
  29520.  
  29521.  See Also
  29522.  
  29523.  LM_SETITEMHEIGHT
  29524.  
  29525.  
  29526.  Changes
  29527.  
  29528.  If the style LS_HORZSCROLL is set, WM_MEASUREITEM must return the length of
  29529.  the list-box item as the high word of the return value.
  29530.  
  29531.  
  29532.  █    WM_MOVE
  29533.  ────────────────────────────────────────────────────────────────────────────
  29534.  
  29535.  
  29536.  WM_MOVE
  29537.  
  29538.  
  29539.  The WM_MOVE message is sent when a window with CS_MOVENOTIFY style changes
  29540.  its absolute position or when a parent window of that window is moved. The
  29541.  window's new position can be obtained by calling the WinQueryWindowPos
  29542.  function.
  29543.  
  29544.  
  29545.  Parameters
  29546.  
  29547.  This message does not use any parameters.
  29548.  
  29549.  
  29550.  Return Value
  29551.  
  29552.  An application should return zero if it processes this message.
  29553.  
  29554.  
  29555.  See Also
  29556.  
  29557.  WinQueryWindowPos
  29558.  
  29559.  
  29560.  Corrections
  29561.  
  29562.  Use the WinQueryWindowPos function, not the WinQueryWindowRect function to
  29563.  obtain the window's position.
  29564.  
  29565.  
  29566.  █    WM_PRESPARAMCHANGED
  29567.  ────────────────────────────────────────────────────────────────────────────
  29568.  
  29569.  
  29570.  WM_PRESPARAMCHANGED idParam = (ULONG) LONGFROMMP(mp1); /*
  29571.  presentation-parameter ID */
  29572.  
  29573.  
  29574.  The WM_PRESPARAMCHANGED message is sent when a presentation parameter has
  29575.  changed.
  29576.  
  29577.  
  29578.  Parameters
  29579.  
  29580.  idParam  Low and high words of mp1. Identifies the presentation parameter
  29581.  that changed. This parameter can be one of the following values:
  29582.  
  29583.  Value                             Meaning
  29584.  ────────────────────────────────────────────────────────────────────────────
  29585.  
  29586.  PP_FOREGROUNDCOLOR                RGB foreground color
  29587.  
  29588.  PP_FOREGROUNDCOLORINDEX           Color index of foreground color
  29589.  
  29590.  PP_BACKGROUNDCOLOR                RGB background color
  29591.  
  29592.  PP_BACKGROUNDCOLORINDEX           Color index of background color
  29593.  
  29594.  PP_HILITEFOREGROUNDCOLOR          RGB color of foreground highlighted area
  29595.  
  29596.  PP_HILITEFOREGROUNDCOLORINDEX     Color index of foreground highlighted
  29597.                                    area
  29598.  
  29599.  PP_HILITEBACKGROUNDCOLOR          RGB color of background highlighted area
  29600.  
  29601.  PP_HILITEBACKGROUNDCOLORINDEX     Color index of background highlighted
  29602.                                    area
  29603.  
  29604.  PP_DISABLEDFOREGROUNDCOLOR        RGB foreground disabled color
  29605.  
  29606.  PP_DISABLEDFOREGROUNDCOLORINDEX   Color index of foreground disabled color
  29607.  
  29608.  PP_DISABLEDBACKGROUNDCOLOR        RGB color of background disabled color
  29609.  
  29610.  PP_DISABLEDBACKGROUNDCOLORINDEX   Color index of background disabled color
  29611.  
  29612.  PP_BORDERCOLOR                    RGB color of window border
  29613.  
  29614.  PP_BORDERCOLORINDEX               Color index of window border
  29615.  
  29616.  PP_FONTNAMESIZE                   Font size
  29617.  
  29618.  
  29619.  
  29620.  See Also
  29621.  
  29622.  WinQueryPresParam, WinSetPresParam
  29623.  
  29624.  
  29625.  █    WM_QUERYHELPINFO
  29626.  ────────────────────────────────────────────────────────────────────────────
  29627.  
  29628.  
  29629.  WM_QUERYHELPINFO
  29630.  
  29631.  
  29632.  The WM_QUERYHELPINFO message is sent to a frame window to retrieve the
  29633.  handle of the help instance.
  29634.  
  29635.  
  29636.  Parameters
  29637.  
  29638.  This message does not use any parameters.
  29639.  
  29640.  
  29641.  Return Value
  29642.  
  29643.  An application should return the help instance handle associated with the
  29644.  window. If no handle is available, the application should return NULL.
  29645.  
  29646.  
  29647.  See Also
  29648.  
  29649.  WM_SETHELPINFO
  29650.  
  29651.  
  29652.  █    WM_SAVEAPPLICATION
  29653.  ────────────────────────────────────────────────────────────────────────────
  29654.  
  29655.  
  29656.  WM_SAVEAPPLICATION
  29657.  mp1 = 0L;    /* not used, must be zero */
  29658.  mp2 = 0L;    /* not used, must be zero */
  29659.  
  29660.  
  29661.  The WM_SAVEAPPLICATION message notifies an application to save its current
  29662.  state (for example, due to a pending system shutdown).
  29663.  
  29664.  
  29665.  Parameters
  29666.  
  29667.  This message does not use any parameters.
  29668.  
  29669.  
  29670.  Comments
  29671.  
  29672.  When a system shutdown is requested, MS OS/2 enumerates the applications in
  29673.  the Task List and sends each application a WM_SAVEAPPLICATION message. The
  29674.  sender of the WM_SAVEAPPLICATION message suspends execution until it
  29675.  receives a reply. The receiving application must not display dialog or
  29676.  message boxes. Doing so could delay the reply and result in unacceptable
  29677.  delays in completing the shutdown.
  29678.  
  29679.  In MS OS/2 versions 1.2 and later, the application must save its state to
  29680.  the os2.ini file by using the WinWriteProfileString or WinWriteProfileData
  29681.  function, or it must save its state to some other file.
  29682.  
  29683.  To be compatible with future releases of MS OS/2, an application should call
  29684.  WinDefWindowProc after processing the WM_SAVEAPPLICATION message.
  29685.  
  29686.  Each application should maintain only one "saved state." If an application
  29687.  receives multiple WM_SAVEAPPLICATION messages, it should overwrite the
  29688.  previous "saved state" with a new "saved state" for each new
  29689.  WM_SAVEAPPLICATION message.
  29690.  
  29691.  
  29692.  See Also
  29693.  
  29694.  WinDefWindowProc, PrfWriteProfileData, PrfWriteProfileString
  29695.  
  29696.  
  29697.  █    WM_SETHELPINFO
  29698.  ────────────────────────────────────────────────────────────────────────────
  29699.  
  29700.  
  29701.  WM_SETHELPINFO
  29702.  hwnd = HWNDFROMMP(mp1);    /* handle of help table */
  29703.  
  29704.  
  29705.  The WM_SETHELPINFO message is sent to a frame window to set the handle of
  29706.  the help instance for that window.
  29707.  
  29708.  
  29709.  Parameters
  29710.  
  29711.  hwnd  Low and high words of mp1. Identifies the help instance.
  29712.  
  29713.  
  29714.  Return Value
  29715.  
  29716.  An application should return zero if it processes this message.
  29717.  
  29718.  
  29719.  See Also
  29720.  
  29721.  WM_QUERYHELPINFO
  29722.  
  29723.  
  29724.  █    WM_WINDOWPOSCHANGED
  29725.  ────────────────────────────────────────────────────────────────────────────
  29726.  
  29727.  
  29728.  WM_WINDOWPOSCHANGED
  29729.  paswp = (PSWP) PVOIDFROMMP(mp1); /* pointer to array of SWP structures */
  29730.  flReturn = MPFROMLONG(mp2);      /* return-value flag                  */
  29731.  
  29732.  
  29733.  The WM_WINDOWPOSCHANGED message is sent whenever the size of a window
  29734.  changes.
  29735.  
  29736.  
  29737.  Parameters
  29738.  
  29739.  paswp  Low and high words of mp1. Points to an array of two SWP structures:
  29740.  the first SWP structure contains the new state of the window; the second SWP
  29741.  structure contains the previous state of the window. The SWP structure has
  29742.  the following form:
  29743.  
  29744.  typedef struct _SWP {
  29745.      USHORT fs;
  29746.      SHORT  cy;
  29747.      SHORT  cx;
  29748.      SHORT  y;
  29749.      SHORT  x;
  29750.      HWND   hwndInsertBehind;
  29751.      HWND   hwnd;
  29752.  } SWP;
  29753.  
  29754.  
  29755.  
  29756.  
  29757.  For a full description, see Chapter 4, "Types, Macros, Structures."
  29758.  
  29759.  flReturn  Specifies the return value of the WM_ADJUSTWINDOWPOS message; it
  29760.  is FALSE if SWP_NOADJUST was specified.
  29761.  
  29762.  
  29763.  Comments
  29764.  
  29765.  The entire window state is filled in both SWP structures; however, the fs
  29766.  field of the first SWP structure contains only those bits that correspond to
  29767.  the actual changes that occurred. For example, if a window is resized,
  29768.  fields x and y contain the position of the window even though it did not
  29769.  move, but the fs field does not contain the SWP_MOVE flag.
  29770.  
  29771.  
  29772.  Example
  29773.  
  29774.  This example processes the WM_WINDOWPOSCHANGED message and assigns the two
  29775.  structures to pointers:
  29776.  
  29777.  PSWP pswpNew, pswpOld;
  29778.  
  29779.  case WM_WINDOWPOSCHANGED:
  29780.      pswpNew = PVOIDFROMMP(mp1);
  29781.      pswpOld = pswpNew + 1;
  29782.  
  29783.  
  29784.  
  29785.  
  29786.  
  29787.  See Also
  29788.  
  29789.  WinCreateWindow, WM_ADJUSTWINDOWPOS, WM_CALCVALIDRECTS
  29790.  
  29791.  
  29792.  
  29793.  
  29794.  
  29795.  Chapter 4  Types, Macros, Structures
  29796.  ────────────────────────────────────────────────────────────────────────────
  29797.  
  29798.  
  29799.  
  29800.  
  29801.  4.1  Introduction
  29802.  
  29803.  This chapter describes the new and updated types, macros, and structures
  29804.  used with the functions and messages in MS OS/2 versions 1.2 and later. For
  29805.  a complete list of the remaining MS OS/2 types, macros, and structures, see
  29806.  the Microsoft Operating System/2 Programmer's Reference, Volume 2 and Volume
  29807.  3.
  29808.  
  29809.  The MS OS/2 functions use many types, macros, and structures that are not
  29810.  part of the standard C language. These types, macros, and structures have
  29811.  been defined to make the task of creating MS OS/2 applications easier and to
  29812.  make applications' sources clearer and easier to understand.
  29813.  
  29814.  All types, macros, and structures in this manual are defined in the MS OS/2
  29815.  C-language include files. You may also want to use these when developing MS
  29816.  OS/2 applications in other computer languages, such as Pascal or assembly
  29817.  language. If include files for a given language are not available, you can
  29818.  translate the definitions given in this chapter by following these
  29819.  guidelines:
  29820.  
  29821.    ■   Numbers must be integers or fixed-point real numbers. MS OS/2
  29822.        functions do not support floating-point numbers. An MS OS/2
  29823.        application can use floating-point numbers as long as an appropriate
  29824.        run-time library or coprocessor is supplied and floating-point numbers
  29825.        are not used as parameters to the MS OS/2 functions.
  29826.  
  29827.    ■   Structures must be packed. Some compilers align each new field in a
  29828.        structure on word or double-word boundaries. This may leave unused
  29829.        bytes in a structure if a given field is smaller than the width
  29830.        between boundaries. MS OS/2 functions require that unused bytes be
  29831.        removed from structures.
  29832.  
  29833.    ■   Reserved fields in structures should be set to zero. Unless otherwise
  29834.        specified, MS OS/2 functions expect reserved fields to be set to zero
  29835.        to avoid compatibility problems with future releases of MS OS/2.
  29836.  
  29837.    ■   Variable-length structures must be supported. Several MS OS/2
  29838.        functions use variable-length structures to receive and/or return
  29839.        information. In a variable-length structure, the number of fields in
  29840.        the structure varies depending on when the structure is used. In the C
  29841.        language, applications typically support variable-length structures by
  29842.        allocating enough memory for the current number of fields and
  29843.        accessing those fields by using a pointer to the structure.
  29844.        Applications in other languages may use this method or devise their
  29845.        own method for supporting variable-length structures.
  29846.  
  29847.    ■   All 16-bit pointers must be relative to an explicitly defined segment
  29848.        register. Some compilers assume that the ds and ss registers contain
  29849.        the same value and implicitly use one segment for both. MS OS/2 does
  29850.        not guarantee that the ds and ss registers will be equal. This is
  29851.        especially true in dynamic-link libraries and programs that use
  29852.        callback functions (for example, window procedures).
  29853.  
  29854.    ■   All 32-bit pointers must consist of a selector:offset pair. MS OS/2
  29855.        functions do not use physical addresses (that is, an address that
  29856.        represents a 32-bit offset from the beginning of physical memory).
  29857.        (One exception to this rule is the VioGetPhysBuf function, which
  29858.        requires a physical address to video memory.)
  29859.  
  29860.  
  29861.  
  29862.  
  29863.  4.2  Types
  29864.  
  29865.  The following MS OS/2 data types are new or have been modified:
  29866.  
  29867.  Type                              Meaning
  29868.  ────────────────────────────────────────────────────────────────────────────
  29869.  
  29870.  HAPP                              32-bit value used as an application
  29871.                                    handle.
  29872.  
  29873.  HINI                              32-bit value used as an
  29874.                                    initialization-file handle.
  29875.  
  29876.  HLIB                              16-bit value used as a module handle.
  29877.  
  29878.  HPROC                             32-bit value used as a pointer to a
  29879.                                    procedure (function).
  29880.  
  29881.  LINE                              32-bit value used as a line number.
  29882.  
  29883.  PHINI                             32-bit value used as a pointer to an
  29884.                                    initialization-file handle.
  29885.  
  29886.  
  29887.  
  29888.  4.3  Macros
  29889.  
  29890.  There are no new or updated MS OS/2 macros.
  29891.  
  29892.  
  29893.  4.4  Structures
  29894.  
  29895.  The following MS OS/2 structures are new or have been modified and can be
  29896.  used by the functions and messages described in the Microsoft Operating
  29897.  System/2 Programmer's Reference.
  29898.  
  29899.  
  29900.  █    ACCEL
  29901.  ────────────────────────────────────────────────────────────────────────────
  29902.  
  29903.  
  29904.  typedef struct _ACCEL {    /* acc */
  29905.      USHORT fs;
  29906.      USHORT key;
  29907.      USHORT cmd;
  29908.  } ACCEL;
  29909.  
  29910.  
  29911.  The ACCEL structure contains an accelerator key used in the ACCELTABLE
  29912.  structure.
  29913.  
  29914.  
  29915.  Fields
  29916.  
  29917.  fs  Specifies the style of the accelerator. This field can be one of the
  29918.  following values:
  29919.  
  29920.  Style                             Meaning
  29921.  ────────────────────────────────────────────────────────────────────────────
  29922.  
  29923.  AF_ALT                            The ALT key must be held down when the
  29924.                                    accelerator key is pressed.
  29925.  
  29926.  AF_CHAR                           The keystroke is a translated character,
  29927.                                    using the code page for the accelerator
  29928.                                    table. This is the default style.
  29929.  
  29930.  AF_CONTROL                        The CTRL key must be held down when the
  29931.                                    accelerator key is pressed.
  29932.  
  29933.  AF_HELP                           The accelerator key generates a WM_HELP
  29934.                                    message instead of a WM_COMMAND message.
  29935.  
  29936.  AF_LONEKEY                        No other key was pressed while the
  29937.                                    accelerator key was down. This style
  29938.                                    typically is used with the ALT key to
  29939.                                    specify that simply pressing and
  29940.                                    releasing the ALT key triggers the
  29941.                                    accelerator.
  29942.  
  29943.  AF_SCANCODE                       The keystroke is an untranslated
  29944.                                    scan-code from the keyboard.
  29945.  
  29946.  AF_SHIFT                          The SHIFT key must be held down when the
  29947.                                    accelerator key is pressed.
  29948.  
  29949.  AF_SYSCOMMAND                     The accelerator key generates the
  29950.                                    message WM_SYSCOMMAND instead of the
  29951.                                    message WM_COMMAND. ,
  29952.  
  29953.  AF_VIRTUALKEY                     The keystroke is a virtual key─for
  29954.                                    example, the F1 key.
  29955.  
  29956.  
  29957.  
  29958.  key  Specifies the accelerator key.
  29959.  
  29960.  cmd  Specifies the value to be placed in the usCmd parameter of the WM_HELP,
  29961.  WM_COMMAND, or WM_SYSCOMMAND message.
  29962.  
  29963.  
  29964.  See Also
  29965.  
  29966.  ACCELTABLE
  29967.  
  29968.  
  29969.  Corrections
  29970.  
  29971.  The fields were listed in an incorrect order. The correct format for this
  29972.  structure is as follows:
  29973.  
  29974.  typedef struct _ACCEL {
  29975.      USHORT fs;
  29976.      USHORT key;
  29977.      USHORT cmd;
  29978.  } ACCEL;
  29979.  
  29980.  
  29981.  
  29982.  
  29983.  
  29984.  █    AVAILDATA
  29985.  ────────────────────────────────────────────────────────────────────────────
  29986.  
  29987.  
  29988.  typedef struct _AVAILDATA {    /* avldt */
  29989.      USHORT  cbpipe;
  29990.      USHORT  cbmessage;
  29991.  } AVAILDATA;
  29992.  
  29993.  
  29994.  The AVAILDATA structure contains information about the bytes in a named
  29995.  pipe.
  29996.  
  29997.  
  29998.  Fields
  29999.  
  30000.  cbpipe  Specifies the number of bytes left in the pipe.
  30001.  
  30002.  cbmessage  Specifies the number of bytes left in the current message.
  30003.  
  30004.  
  30005.  See Also
  30006.  
  30007.  DosPeekNmPipe
  30008.  
  30009.  
  30010.  █    CHARBUNDLE
  30011.  ────────────────────────────────────────────────────────────────────────────
  30012.  
  30013.  
  30014.  typedef struct _CHARBUNDLE {    /* cbnd */
  30015.      LONG    lColor;
  30016.      LONG    lBackColor;
  30017.      USHORT  usMixMode;
  30018.      USHORT  usBackMixMode;
  30019.      USHORT  usSet;
  30020.      USHORT  usPrecision;
  30021.      SIZEF   sizfxCell;
  30022.      POINTL  ptlAngle;
  30023.      POINTL  ptlShear;
  30024.      USHORT  usDirection;
  30025.  } CHARBUNDLE;
  30026.  
  30027.  
  30028.  The CHARBUNDLE structure contains fields that describe the current character
  30029.  attributes in the application's presentation space. MS OS/2 uses these
  30030.  attributes whenever the application draws text using one of the Gpi
  30031.  functions.
  30032.  
  30033.  
  30034.  Fields
  30035.  
  30036.  lColor  Specifies the character foreground color.
  30037.  
  30038.  lBackColor  Specifies the character background color.
  30039.  
  30040.  usMixMode  Specifies the foreground mix mode. MS OS/2 uses this mix mode
  30041.  when it combines the character foreground color and the current
  30042.  drawing-surface color.
  30043.  
  30044.  usBackMixMode  Specifies the background mix mode. MS OS/2 uses this mix mode
  30045.  when it combines the character background color and the current
  30046.  drawing-surface color.
  30047.  
  30048.  usSet  Specifies the character set. This value is the local identifier for
  30049.  the current logical font. It can be any value from 1 through 254.
  30050.  
  30051.  usPrecision  Specifies the current character mode. There are three possible
  30052.  modes: mode 1, mode 2, and mode 3. If mode 1 is set and the current font is
  30053.  an image font, MS OS/2 ignores the current shear, angle, and box attributes.
  30054.  If mode 2 is set and the current font is an image font, MS OS/2 uses the
  30055.  current shear, angle, and box attributes. If mode 3 is set and the current
  30056.  font is an image font, MS OS/2 issues an error message. If the current font
  30057.  is a vector font, MS OS/2 always uses the current shear, angle, and box
  30058.  attributes (regardless of the mode).
  30059.  
  30060.  sizfxCell  Specifies the character-cell size (in world units). This SIZEF
  30061.  structure contains two fixed values.
  30062.  
  30063.  ptlAngle  Points to the POINTL structure that contains the coordinates of
  30064.  the endpoint of the character-angle vector. The baseline of vector
  30065.  characters is drawn parallel to the character-angle vector.
  30066.  
  30067.  ptlShear  Points to the POINTL structure that contains the coordinates of
  30068.  the endpoint of the character-shear vector. The vertical strokes in vector
  30069.  characters are drawn parallel to the character-shear vector.
  30070.  
  30071.  usDirection  Specifies the character direction. The default direction is
  30072.  from left to right. This field can be one of the following values:
  30073.  
  30074.  Value                             Meaning
  30075.  ────────────────────────────────────────────────────────────────────────────
  30076.  
  30077.  CHDIRN_LEFTRIGHT                  Left to right
  30078.  
  30079.  CHDIRN_RIGHTLEFT                  Right to left
  30080.  
  30081.  CHDIRN_TOPBOTTOM                  Top to bottom
  30082.  
  30083.  CHDIRN_BOTTOMTOP                  Bottom to top
  30084.  
  30085.  
  30086.  
  30087.  See Also
  30088.  
  30089.  GpiQueryAttrs, GpiQueryCharAngle, GpiQueryCharBox, GpiQueryCharSet,
  30090.  GpiQueryCp, GpiSetAttrs, GpiSetCharAngle, GpiSetCharBox, GpiSetCharSet,
  30091.  GpiSetCp, POINTL, SIZEF
  30092.  
  30093.  
  30094.  Changes
  30095.  
  30096.  The following character directions can now be specified for the usDirection
  30097.  field:
  30098.  
  30099.  Value                             Meaning
  30100.  ────────────────────────────────────────────────────────────────────────────
  30101.  
  30102.  CHDIRN_LEFTRIGHT                  Left to right
  30103.  
  30104.  CHDIRN_RIGHTLEFT                  Right to left
  30105.  
  30106.  CHDIRN_TOPBOTTOM                  Top to bottom
  30107.  
  30108.  CHDIRN_BOTTOMTOP                  Bottom to top
  30109.  
  30110.  
  30111.  
  30112.  █    DENA1
  30113.  ────────────────────────────────────────────────────────────────────────────
  30114.  
  30115.  
  30116.  typedef struct _DENA1 {    /* dena */
  30117.      UCHAR  reserved;
  30118.      UCHAR  cbName;
  30119.      USHORT cbValue;
  30120.      UCHAR  szName[1];
  30121.  } DENA1;
  30122.  
  30123.  
  30124.  The DENA1 structure contains the names of the extended attributes returned
  30125.  by the DosEnumAttribute function.
  30126.  
  30127.  
  30128.  Fields
  30129.  
  30130.  reserved  Specifies a reserved value; must be zero.
  30131.  
  30132.  cbName  Specifies the length of the extended-attribute name.
  30133.  
  30134.  cbValue  Specifies the length of the extended-attribute value.
  30135.  
  30136.  szName[1]  Contains the name of the extended attribute.
  30137.  
  30138.  
  30139.  See Also
  30140.  
  30141.  DosEnumAttribute
  30142.  
  30143.  
  30144.  █    DEVOPENSTRUC
  30145.  ────────────────────────────────────────────────────────────────────────────
  30146.  
  30147.  
  30148.  typedef struct _DEVOPENSTRUC {    /* dop */
  30149.      PSZ       pszLogAddress;
  30150.      PSZ       pszDriverName;
  30151.      PDRIVDATA pdriv;
  30152.      PSZ       pszDataType;
  30153.      PSZ       pszComment;
  30154.      PSZ       pszQueueProcName;
  30155.      PSZ       pszQueueProcParams;
  30156.      PSZ       pszSpoolerParams;
  30157.      PSZ       pszNetworkParams;
  30158.  } DEVOPENSTRUC;
  30159.  
  30160.  
  30161.  The DEVOPENSTRUC structure describes an output device. A copy of this
  30162.  structure is passed to the DevOpenDC function when a device context is
  30163.  opened.
  30164.  
  30165.  
  30166.  Fields
  30167.  
  30168.  pszLogAddress  Points to the logical device address (for example, lpt1). For
  30169.  OD_QUEUED, it points to a queue name (for example, LPT1Q).
  30170.  
  30171.  pszDriverName  Points to the device driver name (for example, PSCRIPT).
  30172.  
  30173.  pdriv  Points to the DRIVDATA structure that contains device-driver
  30174.  information. This structure identifies the device-driver version number and
  30175.  the device name. It also contains additional device-driver data.
  30176.  
  30177.  pszDataType  Points to the data type of the device-driver (for example,
  30178.  PM_Q_STD).
  30179.  
  30180.  pszComment  Points to a descriptive string associated with the spool file in
  30181.  case of OD_QUEUED.
  30182.  
  30183.  pszQueueProcName  Points to the name of a queue print processor (for
  30184.  example, PMPRINT) in case of OD_QUEUED. If this field is NULL, the system
  30185.  default queue print processor is used.
  30186.  
  30187.  pszQueueProcParams  Points to a queue processor parameter string in case of
  30188.  OD_QUEUED.
  30189.  
  30190.  pszSpoolerParams  Points to a spooler parameter string in case of OD_QUEUED.
  30191.  Each parameter is separated by blanks. The following parameter is defined:
  30192.  
  30193.  Parameter                         Meaning
  30194.  ────────────────────────────────────────────────────────────────────────────
  30195.  
  30196.  PRTY=n:                           Specifies the job priority. The n can be
  30197.                                    any value from 0 for lowest priority to
  30198.                                    99 for highest priority.
  30199.  
  30200.  
  30201.  
  30202.  pszNetworkParams  Points to a network parameter string in case of OD_QUEUED.
  30203.  
  30204.  
  30205.  
  30206.  See Also
  30207.  
  30208.  DevOpenDC
  30209.  
  30210.  
  30211.  Corrections
  30212.  
  30213.  The pszDataType, pszComment, pszQueueProcName, pszQueueProcParams,
  30214.  pszSpoolerParams, and pszNetworkParams fields are used with queued printing.
  30215.  These fields specify information such as the data type of the queued job as
  30216.  well as the queue print processor and parameters to use.
  30217.  
  30218.  
  30219.  █    EAOP
  30220.  ────────────────────────────────────────────────────────────────────────────
  30221.  
  30222.  
  30223.  typedef struct _EAOP {    /* eaop */
  30224.      PGEALIST fpGEAList;
  30225.      PFEALIST fpFEAList;
  30226.      ULONG    oError;
  30227.  } EAOP;
  30228.  
  30229.  
  30230.  The EAOP structure contains extended-attribute information needed by the
  30231.  file-system function calls.
  30232.  
  30233.  
  30234.  Fields
  30235.  
  30236.  fpGEAList  Points to the GEALIST structure that lists the extended
  30237.  attributes to retrieve.
  30238.  
  30239.  fpFEAList  Points to the FEALIST structure that lists the extended
  30240.  attributes found.
  30241.  
  30242.  oError  Specifies the offset, from the beginning of the structure, at which
  30243.  an error occurred.
  30244.  
  30245.  
  30246.  See Also
  30247.  
  30248.  DosFindFirst2, DosMkDir2, DosOpen2, DosQFileInfo, DosQPathInfo,
  30249.  DosSetFileInfo, DosSetPathInfo, FEALIST, GEALIST
  30250.  
  30251.  
  30252.  █    ENTRYFDATA
  30253.  ────────────────────────────────────────────────────────────────────────────
  30254.  
  30255.  
  30256.  typedef struct _ENTRYFDATA {    /* efd */
  30257.      USHORT cb;
  30258.      USHORT cchEditLimit;
  30259.      USHORT ichMinSel;
  30260.      USHORT ichMaxSel;
  30261.  } ENTRYFDATA;
  30262.  
  30263.  
  30264.  The ENTRYFDATA structure contains control data used to specify the
  30265.  characteristics of an entry-field control.
  30266.  
  30267.  
  30268.  Fields
  30269.  
  30270.  cb  Specifies the size of the structure (in bytes). Programs written in the
  30271.  C language should use the sizeof operator to set this field.
  30272.  
  30273.  cchEditLimit  Specifies the maximum number of characters than can be entered
  30274.  in the edit control.
  30275.  
  30276.  ichMinSel  Specifies the beginning point of the current selection within the
  30277.  entry field's text buffer.
  30278.  
  30279.  ichMaxSel  Specifies the end point of the current selection within the entry
  30280.  field's text buffer.
  30281.  
  30282.  
  30283.  █    FATTRS
  30284.  ────────────────────────────────────────────────────────────────────────────
  30285.  
  30286.  
  30287.  typedef struct _FATTRS {    /* fat */
  30288.      USHORT  usRecordLength;
  30289.      USHORT  fsSelection;
  30290.      LONG    lMatch;
  30291.      CHAR    szFacename[FACESIZE];
  30292.      USHORT  idRegistry;
  30293.      USHORT  usCodePage;
  30294.      LONG    lMaxBaselineExt;
  30295.      LONG    lAveCharWidth;
  30296.      USHORT  fsType;
  30297.      USHORT  fsFontUse;
  30298.  } FATTRS;
  30299.  
  30300.  
  30301.  The FATTRS structure specifies the attributes of the logical font to be
  30302.  created by the VioCreateLogFont or GpiCreateLogFont function.
  30303.  
  30304.  
  30305.  Fields
  30306.  
  30307.  usRecordLength  Specifies the length of the structure.
  30308.  
  30309.  fsSelection  Specifies one or more character attributes. This field can be
  30310.  any combination of the following values:
  30311.  
  30312.  Value                             Meaning
  30313.  ────────────────────────────────────────────────────────────────────────────
  30314.  
  30315.  FATTR_SEL_ITALIC                  Specifies italic characters.
  30316.  
  30317.  FATTR_SEL_OUTLINE                 Specifies an outline font.
  30318.  
  30319.  FATTR_SEL_STRIKEOUT               Specifies strikeout characters.
  30320.  
  30321.  FATTR_SEL_UNDERSCORE              Specifies underscored characters.
  30322.  
  30323.  FATTR_SEL_BOLD                    Specifies bold characters.
  30324.  
  30325.  
  30326.  
  30327.  lMatch  Specifies the match number for a specific font. The VioQueryFonts
  30328.  and GpiQueryFonts functions return a unique match number for each font. When
  30329.  this number is specified in the lMatch field, the specified font is used. If
  30330.  the lMatch field is zero, the system determines which font gives the best
  30331.  mapping to the required attributes.
  30332.  
  30333.  szFacename[FACESIZE]  Specifies the typeface name of the font.
  30334.  
  30335.  idRegistry  Specifies the registry number of the font.
  30336.  
  30337.  usCodePage  Specifies the code-page identifier of the font.
  30338.  
  30339.  lMaxBaselineExt  Specifies the sum of the maximum ascender and descender
  30340.  values for a font.
  30341.  
  30342.  lAveCharWidth  Specifies the average width of a character in a font. This
  30343.  value is obtained by multiplying the width of each lowercase letter by a
  30344.  weighted factor, adding the results for all of the letters in the alphabet,
  30345.  and dividing by 1000. The factor corresponds to the frequency of use for a
  30346.  particular letter. For example, the letter e appears frequently in text
  30347.  while the letter q does not; therefore, the factor assigned to e would be
  30348.  greater than the factor assigned to q.
  30349.  
  30350.  fsType  Specifies the type of the font. This field can include one or more
  30351.  of the following values:
  30352.  
  30353.  Value                             Meaning
  30354.  ────────────────────────────────────────────────────────────────────────────
  30355.  
  30356.  FATTR_TYPE_KERNING                Specifies a kerned font.
  30357.  
  30358.  FATTR_TYPE_MBCS                   Specifies a multiple-byte character-set
  30359.                                    font.
  30360.  
  30361.  FATTR_TYPE_DBCS                   Specifies a double-byte character-set
  30362.                                    font.
  30363.  
  30364.  FATTR_TYPE_ANTIALIASED            Specifies an anti-aliased font.
  30365.  
  30366.  
  30367.  
  30368.  fsFontUse  Specifies how the font is related to the character attributes.
  30369.  This field can be any combination of the following values:
  30370.  
  30371.  Value                             Meaning
  30372.  ────────────────────────────────────────────────────────────────────────────
  30373.  
  30374.  FATTR_FONTUSE_NOMIX               The application cannot mix text and
  30375.                                    graphics.
  30376.  
  30377.  FATTR_FONTUSE_OUTLINE             Requests an outline font.
  30378.  
  30379.  FATTR_FONTUSE_TRANSFORMABLE       Requests a transformable font.
  30380.  
  30381.  
  30382.  
  30383.  See Also
  30384.  
  30385.  GpiCreateLogFont, GpiQueryFonts, VioCreateLogFont, VioQueryFonts
  30386.  
  30387.  
  30388.  Changes
  30389.  
  30390.  FATTR_TYPE_FIXED can no longer be specified for the fsType field. The
  30391.  following new constants can be specified for fsType:
  30392.  
  30393.  Value                             Meaning
  30394.  ────────────────────────────────────────────────────────────────────────────
  30395.  
  30396.  FATTR_TYPE_MBCS                   Specifies a multiple-byte character-set
  30397.                                    font.
  30398.  
  30399.  FATTR_TYPE_DBCS                   Specifies a double-byte character-set
  30400.                                    font.
  30401.  
  30402.  FATTR_TYPE_ANTIALIASED            Specifies an anti-aliased font.
  30403.  
  30404.  
  30405.  
  30406.  FATTR_SEL_OUTLINE can be specified for the fsSelection field.
  30407.  
  30408.  
  30409.  Corrections
  30410.  
  30411.  The FATTR_SEL_HOLLOW constant did not exist in the include files. A new
  30412.  constant, FATTR_SEL_OUTLINE, gives you hollow (outlined) characters.
  30413.  
  30414.  
  30415.  █    FEA
  30416.  ────────────────────────────────────────────────────────────────────────────
  30417.  
  30418.  
  30419.  typedef struct _FEA {    /* fea */
  30420.      BYTE   fEA;
  30421.      BYTE   cbName;
  30422.      USHORT cbValue;
  30423.  } FEA;
  30424.  
  30425.  
  30426.  The FEA structure contains the values of extended attributes.
  30427.  
  30428.  
  30429.  Fields
  30430.  
  30431.  fEA  Specifies one or more flags. In MS OS/2 versions 1.2 and later, the
  30432.  only flag available is FEA_NEEDEA, indicating an extended-attribute bit is
  30433.  needed.
  30434.  
  30435.  cbName  Specifies the length of the extended-attribute name, not including
  30436.  the null terminating character.
  30437.  
  30438.  cbValue  Specifies the length of the extended-attribute value.
  30439.  
  30440.  
  30441.  Comments
  30442.  
  30443.  This structure also contains a variable-length portion immediately following
  30444.  the cbValue field. This variable-length portion contains the
  30445.  extended-attribute name and the extended-attribute value.
  30446.  
  30447.  
  30448.  See Also
  30449.  
  30450.  EAOP, FEALIST, GEA, GEALIST
  30451.  
  30452.  
  30453.  █    FEALIST
  30454.  ────────────────────────────────────────────────────────────────────────────
  30455.  
  30456.  
  30457.  typedef struct _FEALIST {    /* feal */
  30458.      ULONG cbList;
  30459.      FEA   list[1];
  30460.  } FEALIST;
  30461.  
  30462.  
  30463.  The FEALIST structure contains one or more extended attributes.
  30464.  
  30465.  
  30466.  Fields
  30467.  
  30468.  cbList  Specifies the size (in bytes) of the structure.
  30469.  
  30470.  list[1]  Contains an array of one or more FEA structures.
  30471.  
  30472.  
  30473.  Comments
  30474.  
  30475.  The FEALIST structure contains a list of the extended attributes that were
  30476.  found. The GEALIST structure contains names of extended attributes to
  30477.  retrieve information for.
  30478.  
  30479.  
  30480.  See Also
  30481.  
  30482.  DosFindFirst2, DosMkDir2, DosOpen2, DosQPathInfo, DosSetFileInfo,
  30483.  DosSetPathInfo, EAOP, FEA, GEALIST
  30484.  
  30485.  
  30486.  █    FILEFINDBUF2
  30487.  ────────────────────────────────────────────────────────────────────────────
  30488.  
  30489.  
  30490.  typedef struct _FILEFINDBUF2 {    /* findbuf2 */
  30491.      FDATE  fdateCreation;
  30492.      FTIME  ftimeCreation;
  30493.      FDATE  fdateLastAccess;
  30494.      FTIME  ftimeLastAccess;
  30495.      FDATE  fdateLastWrite;
  30496.      FTIME  ftimeLastWrite;
  30497.      ULONG  cbFile;
  30498.      ULONG  cbFileAlloc;
  30499.      USHORT attrFile;
  30500.      ULONG  cbList;
  30501.      UCHAR  cchName;
  30502.      CHAR   achName[CCHMAXPATHCOMP];
  30503.  } FILEFINDBUF2;
  30504.  
  30505.  
  30506.  The FILEFINDBUF2 structure contains information about a file.
  30507.  
  30508.  
  30509.  Fields
  30510.  
  30511.  fdateCreation  Specifies the date the file was created.
  30512.  
  30513.  ftimeCreation  Specifies the time the file was created.
  30514.  
  30515.  fdateLastAccess  Specifies the date the file was last accessed.
  30516.  
  30517.  ftimeLastAccess  Specifies the time the file was last accessed.
  30518.  
  30519.  fdateLastWrite  Specifies the date the file was last written to.
  30520.  
  30521.  ftimeLastWrite  Specifies the time the file was last written to.
  30522.  
  30523.  cbFile  Specifies the end of file data.
  30524.  
  30525.  cbFileAlloc  Specifies the allocated file size.
  30526.  
  30527.  attrFile  Specifies the file attributes.
  30528.  
  30529.  cbList  Specifies the size (in bytes) of the buffer needed for the list of
  30530.  extended attributes in a FIL_QUERYEASFROMLIST level request (see the
  30531.  DosFindFirst2 function).
  30532.  
  30533.  cchName  Specifies the length of the null-terminated filename.
  30534.  
  30535.  achName[CCHMAXPATHCOMP]  Specifies the null-terminated filename.
  30536.  
  30537.  
  30538.  See Also
  30539.  
  30540.  DosFindFirst2, FDATE, FTIME
  30541.  
  30542.  
  30543.  █    FILESTATUS2
  30544.  ────────────────────────────────────────────────────────────────────────────
  30545.  
  30546.  
  30547.  typedef struct _FILESTATUS2 {    /* fsts2 */
  30548.      FDATE   fdateCreation;
  30549.      FTIME   ftimeCreation;
  30550.      FDATE   fdateLastAccess;
  30551.      FTIME   ftimeLastAccess;
  30552.      FDATE   fdateLastWrite;
  30553.      FTIME   ftimeLastWrite;
  30554.      ULONG   cbFile;
  30555.      ULONG   cbFileAlloc;
  30556.      USHORT  attrFile;
  30557.      ULONG   cbList;
  30558.  } FILESTATUS2;
  30559.  
  30560.  
  30561.  The FILESTATUS2 structure contains information about the status of a file.
  30562.  
  30563.  
  30564.  Fields
  30565.  
  30566.  fdateCreation  Specifies the date the file was created.
  30567.  
  30568.  ftimeCreation  Specifies the time the file was created.
  30569.  
  30570.  fdateLastAccess  Specifies the date the file was last accessed.
  30571.  
  30572.  ftimeLastAccess  Specifies the time the file was last accessed.
  30573.  
  30574.  fdateLastWrite  Specifies the date the file was last written to.
  30575.  
  30576.  ftimeLastWrite  Specifies the time the file was last written to.
  30577.  
  30578.  cbFile  Specifies the end of file data.
  30579.  
  30580.  cbFileAlloc  Specifies the allocated file size.
  30581.  
  30582.  attrFile  Specifies the file attributes.
  30583.  
  30584.  cbList  Specifies the size of the extended-attribute buffer.
  30585.  
  30586.  
  30587.  Comments
  30588.  
  30589.  The cbFile, cbFileAlloc, and attrFile fields are not used by the
  30590.  DosSetFileInfo function.
  30591.  
  30592.  
  30593.  See Also
  30594.  
  30595.  DosQFileInfo, DosQPathInfo, DosSetFileInfo
  30596.  
  30597.  
  30598.  █    FIOLOCKCMD
  30599.  ────────────────────────────────────────────────────────────────────────────
  30600.  
  30601.  
  30602.  typedef struct _FIOLOCKCMD {    /* flc */
  30603.      USHORT  usCmd;
  30604.      USHORT  cLockCnt;
  30605.      ULONG   cTimeOut;
  30606.  } FIOLOCKCMD;
  30607.  
  30608.  
  30609.  The FIOLOCKCMD structure contains information used by the DosFileIO function
  30610.  for locking a file.
  30611.  
  30612.  
  30613.  Fields
  30614.  
  30615.  usCmd  Specifies the command to pass to the DosFileIO function. This field
  30616.  should be set to FIO_LOCK.
  30617.  
  30618.  cLockCnt  Specifies the number of FIOLOCKREC structures that follow this
  30619.  structure. An FIOLOCKREC structure specifies the area of the file to lock
  30620.  and whether another process can read the locked portion.
  30621.  
  30622.  cTimeOut  Specifies the time-out period (in milliseconds). If this field is
  30623.  NULL, the DosFileIO function continues immediately with the next command. If
  30624.  this field is -1, DosFileIO waits indefinitely for the requested lock to
  30625.  become available. Any other value specifies the maximum amount of time
  30626.  DosFileIO waits for the requested lock to become available.
  30627.  
  30628.  
  30629.  See Also
  30630.  
  30631.  DosFileIO, DosFileLocks, FIOLOCKREC
  30632.  
  30633.  
  30634.  █    FIOLOCKREC
  30635.  ────────────────────────────────────────────────────────────────────────────
  30636.  
  30637.  
  30638.  typedef struct _FIOLOCKREC {    /* flr */
  30639.      USHORT  fShare;
  30640.      ULONG   cbStart;
  30641.      ULONG   cbLength;
  30642.  } FIOLOCKREC;
  30643.  
  30644.  
  30645.  The FIOLOCKREC structure contains information used by the DosFileIO function
  30646.  for locking a file. This structure is preceded by an FIOLOCKCMD structure
  30647.  that specifies the number of FIOLOCKREC structures to be used.
  30648.  
  30649.  
  30650.  Fields
  30651.  
  30652.  fShare  Specifies whether other processes can read the portion of the file
  30653.  that is locked. A value of FIO_SHAREREAD allows other processes to read the
  30654.  file; a value of FIO_NOSHARE prevents other processes from reading the file.
  30655.  
  30656.  
  30657.  cbStart  Specifies the offset of the lock region. The offset is established
  30658.  from the beginning of the file.
  30659.  
  30660.  cbLength  Specifies the length (in bytes) of the region to be locked.
  30661.  
  30662.  
  30663.  See Also
  30664.  
  30665.  DosFileIO, FIOLOCKCMD
  30666.  
  30667.  
  30668.  █    FIOREADWRITE
  30669.  ────────────────────────────────────────────────────────────────────────────
  30670.  
  30671.  
  30672.  typedef struct _FIOREADWRITE {    /* frwc */
  30673.      USHORT usCmd;
  30674.      PVOID  pbBuffer;
  30675.      USHORT cbBufferLen;
  30676.      USHORT cbActualLen;
  30677.  } FIOREADWRITE;
  30678.  
  30679.  
  30680.  The FIOREADWRITE structure contains information used by the DosFileIO
  30681.  function for reading and writing data.
  30682.  
  30683.  
  30684.  Fields
  30685.  
  30686.  usCmd  Specifies the command to pass to the DosFileIO function. This field
  30687.  should be set to FIO_READ for a read operation or to FIO_WRITE for a write
  30688.  operation.
  30689.  
  30690.  pbBuffer  Points to the buffer that contains the data to be written, or
  30691.  points to a buffer that receives the data that is read.
  30692.  
  30693.  cbBufferLen  Specifies the length of the buffer (in bytes).
  30694.  
  30695.  cbActualLen  Specifies the number of bytes actually transferred.
  30696.  
  30697.  
  30698.  See Also
  30699.  
  30700.  DosFileIO
  30701.  
  30702.  
  30703.  █    FIOSEEKCMD
  30704.  ────────────────────────────────────────────────────────────────────────────
  30705.  
  30706.  
  30707.  typedef struct _FIOSEEKCMD {    /* fsc */
  30708.      USHORT  usCmd;
  30709.      USHORT  fsMethod;
  30710.      ULONG   cbDistance;
  30711.      ULONG   cbNewPosition;
  30712.  } FIOSEEKCMD;
  30713.  
  30714.  
  30715.  The FIOSEEKCMD structure contains information used by the DosFileIO
  30716.  function's seek operation.
  30717.  
  30718.  
  30719.  Fields
  30720.  
  30721.  usCmd  Specifies the command to be passed to the DosFileIO function. This
  30722.  field must be set to FIO_SEEK.
  30723.  
  30724.  fsMethod  Specifies where to begin the seek operation. This field can be one
  30725.  of the following values:
  30726.  
  30727.  Value                             Meaning
  30728.  ────────────────────────────────────────────────────────────────────────────
  30729.  
  30730.  FILE_BEGIN                        Start at the beginning of the file.
  30731.  
  30732.  FILE_CURRENT                      Start at the current location.
  30733.  
  30734.  FILE_END                          Start at the end of the file.
  30735.  
  30736.  
  30737.  
  30738.  cbDistance  Specifies the new position requested for the file pointer. The
  30739.  value of this field is the number of bytes offset from the starting position
  30740.  specified in the fsMethod field.
  30741.  
  30742.  cbNewPosition  On return from the DosFileIO function, this field contains
  30743.  the new position of the file pointer relative to the beginning of the file.
  30744.  
  30745.  
  30746.  See Also
  30747.  
  30748.  DosChgFilePtr, DosFileIO
  30749.  
  30750.  
  30751.  █    FIOUNLOCKCMD
  30752.  ────────────────────────────────────────────────────────────────────────────
  30753.  
  30754.  
  30755.  typedef struct _FIOUNLOCKCMD {    /* fuc */
  30756.      USHORT  usCmd;
  30757.      USHORT  cUnlockCnt;
  30758.  } FIOUNLOCKCMD;
  30759.  
  30760.  
  30761.  The FIOUNLOCKCMD structure contains information used by the DosFileIO
  30762.  function for unlocking a file.
  30763.  
  30764.  
  30765.  Fields
  30766.  
  30767.  usCmd  Specifies the command to pass to the DosFileIO function. This field
  30768.  must be set to FIO_UNLOCK.
  30769.  
  30770.  cUnlockCnt  Specifies the number of FIOUNLOCKREC structures that follow this
  30771.  structure.
  30772.  
  30773.  
  30774.  See Also
  30775.  
  30776.  DosFileIO, DosFileLocks, FIOUNLOCKREC
  30777.  
  30778.  
  30779.  █    FIOUNLOCKREC
  30780.  ────────────────────────────────────────────────────────────────────────────
  30781.  
  30782.  
  30783.  typedef struct _FIOUNLOCKREC {    /* fur */
  30784.      ULONG   cbStart;
  30785.      ULONG   cbLength;
  30786.  } FIOUNLOCKREC;
  30787.  
  30788.  
  30789.  The FIOUNLOCKREC structure contains information used by the DosFileIO
  30790.  function for unlocking a file. An FIOUNLOCKCMD structure precedes this
  30791.  structure and specifies the number of FIOUNLOCKREC structures that are used.
  30792.  
  30793.  
  30794.  
  30795.  Fields
  30796.  
  30797.  cbStart  Specifies the offset of the unlock region. The offset is determined
  30798.  from the beginning of the file.
  30799.  
  30800.  cbLength  Specifies the length (in bytes) of the region to unlock.
  30801.  
  30802.  
  30803.  See Also
  30804.  
  30805.  DosFileIO, FIOUNLOCKCMD
  30806.  
  30807.  
  30808.  █    FONTMETRICS
  30809.  ────────────────────────────────────────────────────────────────────────────
  30810.  
  30811.  
  30812.  typedef struct _FONTMETRICS {    /* fm */
  30813.      CHAR    szFamilyname[FACESIZE];
  30814.      CHAR    szFacename[FACESIZE];
  30815.      USHORT  idRegistry;
  30816.      USHORT  usCodePage;
  30817.      LONG    lEmHeight;
  30818.      LONG    lXHeight;
  30819.      LONG    lMaxAscender;
  30820.      LONG    lMaxDescender;
  30821.      LONG    lLowerCaseAscent;
  30822.      LONG    lLowerCaseDescent;
  30823.      LONG    lInternalLeading;
  30824.      LONG    lExternalLeading;
  30825.      LONG    lAveCharWidth;
  30826.      LONG    lMaxCharInc;
  30827.      LONG    lEmInc;
  30828.      LONG    lMaxBaselineExt;
  30829.      SHORT   sCharSlope;
  30830.      SHORT   sInlineDir;
  30831.      SHORT   sCharRot;
  30832.      USHORT  usWeightClass;
  30833.      USHORT  usWidthClass;
  30834.      SHORT   sXDeviceRes;
  30835.      SHORT   sYDeviceRes;
  30836.      SHORT   sFirstChar;
  30837.      SHORT   sLastChar;
  30838.      SHORT   sDefaultChar;
  30839.      SHORT   sBreakChar;
  30840.      SHORT   sNominalPointSize;
  30841.      SHORT   sMinimumPointSize;
  30842.      SHORT   sMaximumPointSize;
  30843.      USHORT  fsType;
  30844.      USHORT  fsDefn;
  30845.      USHORT  fsSelection;
  30846.      USHORT  fsCapabilities;
  30847.      LONG    lSubscriptXSize;
  30848.      LONG    lSubscriptYSize;
  30849.      LONG    lSubscriptXOffset;
  30850.      LONG    lSubscriptYOffset;
  30851.      LONG    lSuperscriptXSize;
  30852.      LONG    lSuperscriptYSize;
  30853.      LONG    lSuperscriptXOffset;
  30854.      LONG    lSuperscriptYOffset;
  30855.      LONG    lUnderscoreSize;
  30856.      LONG    lUnderscorePosition;
  30857.      LONG    lStrikeoutSize;
  30858.      LONG    lStrikeoutPosition;
  30859.      SHORT   sKerningPairs;
  30860.      SHORT   sFamilyClass;
  30861.      LONG    lMatch;
  30862.  } FONTMETRICS;
  30863.  
  30864.  
  30865.  The FONTMETRICS structure contains information about fonts.
  30866.  
  30867.  
  30868.  Fields
  30869.  
  30870.  szFamilyname[FACESIZE]  Specifies the family name of the font. Examples of
  30871.  common family names are Courier, Swiss, and Roman.
  30872.  
  30873.  szFacename[FACESIZE]  Specifies the typeface name of the font. Examples of
  30874.  common typeface names are Courier, Helv, System Monospaced, System
  30875.  Proportional, and Times Roman.
  30876.  
  30877.  idRegistry  Specifies the registry number of the font.
  30878.  
  30879.  usCodePage  Identifies the code page an application should use with a
  30880.  particular font.
  30881.  
  30882.  lEmHeight  Specifies the average height of uppercase characters. The height
  30883.  is measured in world coordinates from the baseline to the top of the
  30884.  character.
  30885.  
  30886.  lXHeight  Specifies the average height of lowercase characters. The height
  30887.  is measured in world coordinates from the baseline to the top of the
  30888.  character.
  30889.  
  30890.  lMaxAscender  Specifies the maximum height of any character in the font. The
  30891.  height is measured in world coordinates from the baseline to the top of the
  30892.  character.
  30893.  
  30894.  lMaxDescender  Specifies the maximum depth of any character in the font. The
  30895.  depth is measured in world coordinates from the baseline to the bottom of
  30896.  the deepest character.
  30897.  
  30898.  lLowerCaseAscent  Specifies the maximum height of any lowercase character in
  30899.  the font. The height is measured in world coordinates from the baseline to
  30900.  the top of the ascender of the tallest lowercase character.
  30901.  
  30902.  lLowerCaseDescent  Specifies the maximum depth of any lowercase character in
  30903.  a font. The depth is measured in world coordinates from the baseline to the
  30904.  bottom of the descender on the deepest lowercase character.
  30905.  
  30906.  lInternalLeading  Specifies the amount of space reserved in the top of each
  30907.  character cell for accent marks. This metric is always given in world
  30908.  coordinates.
  30909.  
  30910.  lExternalLeading  Specifies the amount of space that should appear between
  30911.  adjacent rows of text. This metric is always given in world coordinates.
  30912.  
  30913.  lAveCharWidth  Specifies the average character width for characters in the
  30914.  font. The average character width is determined by multiplying the width of
  30915.  each lowercase character by a predetermined constant, adding the results,
  30916.  and then dividing by 1000. Following are the letters and their predetermined
  30917.  constants:
  30918.  
  30919.      a     64        j     3        s         56
  30920.      b     14        k     6        t         71
  30921.      c     27        l    35        u         31
  30922.      d     35        m    20        v         10
  30923.      e    100        n    56        w         18
  30924.      f     20        o    56        x          3
  30925.      g     14        p    17        y         18
  30926.      h     42        q     4        z          2
  30927.      i     63        r    49        space    166
  30928.  
  30929.  
  30930.  
  30931.  
  30932.  lMaxCharInc  Specifies the maximum increment between characters in the font.
  30933.  
  30934.  
  30935.  lEmInc  Specifies the width of an uppercase M in the font.
  30936.  
  30937.  lMaxBaselineExt  Specifies the sum of the maximum ascender and maximum
  30938.  descender values.
  30939.  
  30940.  sCharSlope  Specifies the angle (in degrees and minutes) between a vertical
  30941.  line and the upright strokes in characters in the font. The first nine bits
  30942.  of this value contain the degrees, the next six bits contain the minutes,
  30943.  and the last bit is reserved. The slope of characters in a normal font is
  30944.  zero; the slope of italic characters is nonzero.
  30945.  
  30946.  sInlineDir  Specifies an angle (in degrees and minutes, increasing
  30947.  clockwise) from the x-axis that the system uses when it draws a text string.
  30948.  The system draws each consecutive character from the text string in the
  30949.  in-line direction. The in-line direction for a Swiss font is zero; the
  30950.  in-line direction for a Hebrew font is 180.
  30951.  
  30952.  sCharRot  Specifies the angle (in degrees and minutes) between the baseline
  30953.  of characters in the font and the x-axis. This is the angle assigned by the
  30954.  font designer.
  30955.  
  30956.  usWeightClass  Specifies the thickness of the strokes that form the
  30957.  characters in the font. This field can be one of the following values:
  30958.  
  30959.  Value                             Meaning
  30960.  ────────────────────────────────────────────────────────────────────────────
  30961.  
  30962.  1                                 Ultra-light
  30963.  
  30964.  2                                 Extra-light
  30965.  
  30966.  3                                 Light
  30967.  
  30968.  4                                 Semi-light
  30969.  
  30970.  5                                 Medium (normal)
  30971.  
  30972.  6                                 Semi-bold
  30973.  
  30974.  7                                 Bold
  30975.  
  30976.  8                                 Extra-bold
  30977.  
  30978.  9                                 Ultra-bold
  30979.  
  30980.  
  30981.  
  30982.  usWidthClass  Specifies the relative aspect ratio of characters in the font
  30983.  in relation to the normal aspect ratio for a font of this type. The
  30984.  following are the possible values:
  30985.  
  30986.  Value                             Descriptio  Normal aspect ratio
  30987.                                    n
  30988.  ────────────────────────────────────────────────────────────────────────────
  30989.  
  30990.  1                                 Ultra-cond  50%
  30991.                                    ensed
  30992.  
  30993.  2                                 Extra-cond  62.5%
  30994.                                    ensed
  30995.  
  30996.  3                                 Condensed   75%
  30997.  
  30998.  4                                 Semi-conde  87.5%
  30999.                                    nsed
  31000.  
  31001.  5                                 Normal      100%
  31002.  
  31003.  6                                 Semi-expan  112.5%
  31004.                                    ded
  31005.  
  31006.  7                                 Expanded    125%
  31007.  
  31008.  8                                 Extra-expa  150%
  31009.                                    nded
  31010.  
  31011.  9                                 Ultra-expa  200%
  31012.                                    nded
  31013.  
  31014.  
  31015.  
  31016.  sXDeviceRes  Specifies the horizontal resolution of the target device for
  31017.  which the font was originally designed. This value is given in pels per
  31018.  inch.
  31019.  
  31020.  sYDeviceRes  Specifies the vertical resolution of the target device for
  31021.  which the font was originally designed. This value is given in pels per
  31022.  inch.
  31023.  
  31024.  sFirstChar  Specifies the code point for the first character in the font.
  31025.  
  31026.  sLastChar  Specifies the code point for the last character in the font. This
  31027.  code point is an offset from the sFirstChar value.
  31028.  
  31029.  sDefaultChar  Specifies the code point for the default character in the
  31030.  font. This code point is an offset from the sDefaultChar value. The default
  31031.  character is the character the system uses when an application specifies a
  31032.  code point that is out of the range of a font's code page.
  31033.  
  31034.  sBreakChar  Specifies the code point for the space character in the font.
  31035.  This code point is an offset from the sFirstChar value.
  31036.  
  31037.  sNominalPointSize  Specifies the height of the font (in decipoints─each
  31038.  decipoint is 1/720 inch). The nominal point size is the point size in which
  31039.  the font was designed to be drawn.
  31040.  
  31041.  sMinimumPointSize  Specifies the minimum height of the font (in decipoints).
  31042.  A font should not be reduced to a size smaller than the minimum point size.
  31043.  
  31044.  sMaximumPointSize  Specifies the maximum height of the font (in decipoints).
  31045.  A font should not be increased to a size larger than this value.
  31046.  
  31047.  fsType  Specifies the type of font. This field can be one or more of the
  31048.  following values:
  31049.  
  31050.  Value                             Meaning
  31051.  ────────────────────────────────────────────────────────────────────────────
  31052.  
  31053.  FM_TYPE_FIXED                     Font is fixed. Font is proportional if
  31054.                                    this value is not specified.
  31055.  
  31056.  FM_TYPE_LICENSED                  Font is licensed.
  31057.  
  31058.  FM_TYPE_KERNING                   Font has kerning information.
  31059.  
  31060.  FM_TYPE_DBCS                      Font is a double-byte character set.
  31061.  
  31062.  FM_TYPE_MBCS                      Font is a multiple-byte character set.
  31063.  
  31064.  FM_TYPE_64K                       Font requires more than 64K of memory.
  31065.  
  31066.  
  31067.  
  31068.  fsDefn  Specifies the definition of the font. This field can be one of the
  31069.  following values:
  31070.  
  31071.  Value                             Meaning
  31072.  ────────────────────────────────────────────────────────────────────────────
  31073.  
  31074.  FM_DEFN_OUTLINE                   Specifies an outline font (vector).
  31075.  
  31076.  FM_DEFN_GENERIC                   Specifies a generic font (raster or
  31077.                                    bitmapped).
  31078.  
  31079.  
  31080.  
  31081.  fsSelection  Specifies how the characters are to be drawn. This field can be
  31082.  one or more of the following values:
  31083.  
  31084.  Value                             Meaning
  31085.  ────────────────────────────────────────────────────────────────────────────
  31086.  
  31087.  FM_SEL_ITALIC                     Characters are italic.
  31088.  
  31089.  FM_SEL_UNDERSCORE                 Characters are underscored.
  31090.  
  31091.  FM_SEL_NEGATIVE                   Characters are drawn using negative
  31092.                                    images.
  31093.  
  31094.  FM_SEL_OUTLINE                    Characters are outlined.
  31095.  
  31096.  FM_SEL_STRIKEOUT                  Characters are overstruck.
  31097.  
  31098.  FM_SEL_BOLD                       Characters are bold.
  31099.  
  31100.  
  31101.  
  31102.  fsCapabilities  Specifies whether the characters in this font can be mixed
  31103.  with graphics. If this field is FM_CAP_NOMIX, the characters cannot be mixed
  31104.  with graphics; otherwise, they can be mixed with graphics.
  31105.  
  31106.  lSubscriptXSize  Specifies the horizontal size (in world coordinates) for
  31107.  subscripts in the font.
  31108.  
  31109.  lSubscriptYSize  Specifies the vertical size (in world coordinates) for
  31110.  subscripts in the font.
  31111.  
  31112.  lSubscriptXOffset  Specifies the horizontal offset from the left edge of the
  31113.  character cell.
  31114.  
  31115.  lSubscriptYOffset  Specifies the vertical offset from the character-cell
  31116.  baseline.
  31117.  
  31118.  lSuperscriptXSize  Specifies the horizontal size (in world coordinates) for
  31119.  superscripts in the font.
  31120.  
  31121.  lSuperscriptYSize  Specifies the vertical size (in world coordinates) for
  31122.  superscripts in the font.
  31123.  
  31124.  lSuperscriptXOffset  Specifies the horizontal offset from the left edge of
  31125.  the character cell.
  31126.  
  31127.  lSuperscriptYOffset  Specifies the vertical offset from the character-cell
  31128.  baseline.
  31129.  
  31130.  lUnderscoreSize  Specifies the width of the underscore (in world
  31131.  coordinates).
  31132.  
  31133.  lUnderscorePosition  Specifies the distance from the baseline to the
  31134.  underscore line (in world coordinates).
  31135.  
  31136.  lStrikeoutSize  Specifies the width of the overstrike (in world
  31137.  coordinates).
  31138.  
  31139.  lStrikeoutPosition  Specifies the position of the overstrike in relation to
  31140.  the baseline.
  31141.  
  31142.  sKerningPairs  Specifies the number of kerning pairs in the kerning-pair
  31143.  table for the font.
  31144.  
  31145.  sFamilyClass  Specifies the font-family class and subclass.
  31146.  
  31147.  lMatch  Specifies a long integer that identifies this font. The application
  31148.  should copy this value to the FATTRS structure when the GpiCreateLogFont
  31149.  function is called.
  31150.  
  31151.  
  31152.  See Also
  31153.  
  31154.  GpiCreateLogFont, GpiQueryFontMetrics, GpiQueryFonts, VioQueryFonts
  31155.  
  31156.  
  31157.  Changes
  31158.  
  31159.  New constants have been added for the fsType, fsDefn, and fsSelection.
  31160.  
  31161.  
  31162.  Corrections
  31163.  
  31164.  The sReserved field has been replaced with the sFamilyClass field.
  31165.  
  31166.  Common family names for the szFamilyname field are Courier, Swiss, and
  31167.  Roman. Common typeface names for the szFacename field are Courier, Helv,
  31168.  System Monospaced, System Proportional, and Times Roman.
  31169.  
  31170.  
  31171.  █    FSINFO
  31172.  ────────────────────────────────────────────────────────────────────────────
  31173.  
  31174.  
  31175.  typedef struct _FSINFO {    /* fsinf */
  31176.      ULONG       ulVSN;
  31177.      VOLUMELABEL vol;
  31178.  } FSINFO;
  31179.  
  31180.  
  31181.  The FSINFO structure contains information about the volume label of a disk.
  31182.  
  31183.  
  31184.  Fields
  31185.  
  31186.  ulVSN  Specifies the serial number of the disk. If there is no serial number
  31187.  on the disk, this field is zero.
  31188.  
  31189.  vol  Specifies a VOLUMELABEL structure that will contain the name of the
  31190.  volume label.
  31191.  
  31192.  
  31193.  See Also
  31194.  
  31195.  DosQFSInfo, VOLUMELABEL
  31196.  
  31197.  
  31198.  Changes
  31199.  
  31200.  The fields fdateCreation and ftimeCreation worked only for MS OS/2 version
  31201.  1.1. These fields have been replaced by the ulVSN field, which receives the
  31202.  serial number of the disk for MS OS/2 versions 1.2 and later.
  31203.  
  31204.  
  31205.  █    FSQBUFFER
  31206.  ────────────────────────────────────────────────────────────────────────────
  31207.  
  31208.  
  31209.  typedef struct _FSQBUFFER {    /* fsqbf */
  31210.      USHORT  iType;
  31211.      USHORT  cbName;
  31212.      UCHAR   szName[1];
  31213.      USHORT  cbFSDName;
  31214.      UCHAR   szFSDName[1];
  31215.      USHORT  cbFSAData;
  31216.      UCHAR   rgFSAData[1];
  31217.  } FSQBUFFER;
  31218.  
  31219.  
  31220.  The FSQBUFFER structure contains information about the file system attached
  31221.  to a driver or device.
  31222.  
  31223.  
  31224.  Fields
  31225.  
  31226.  iType  Specifies the type of device. This field can contain one of the
  31227.  following values:
  31228.  
  31229.  Value                             Type
  31230.  ────────────────────────────────────────────────────────────────────────────
  31231.  
  31232.  FSAT_CHARDEV                      Resident character device
  31233.  
  31234.  FSAT_PSEUDODEV                    Pseudo-character device
  31235.  
  31236.  FSAT_LOCALDRV                     Local drive
  31237.  
  31238.  FSAT_REMOTEDRV                    Remote drive attached to a file system
  31239.  
  31240.  
  31241.  
  31242.  cbName  Specifies the length of the drive or device name, not including the
  31243.  null terminating character.
  31244.  
  31245.  szName[1]  Specifies the drive or device name. The actual length of this
  31246.  field varies, depending on the length of the device name.
  31247.  
  31248.  cbFSDName  Specifies the length of the file-system name, not including the
  31249.  null terminating character.
  31250.  
  31251.  szFSDName[1]  Specifies the file-system name the drive or device is attached
  31252.  to. The actual length of this field varies depending on the length of the
  31253.  file-system name. This field contains only a null character if the device is
  31254.  a resident character device.
  31255.  
  31256.  cbFSAData  Specifies the length of the data returned by the file system.
  31257.  
  31258.  rgFSAData[1]  Specifies the data returned by the file system. The actual
  31259.  length and meaning of this field varies, depending on the file system that
  31260.  is attached.
  31261.  
  31262.  
  31263.  Comments
  31264.  
  31265.  This structure should be used only as a guideline. Because it contains
  31266.  variable-length fields, it cannot be used directly to retrieve the data.
  31267.  
  31268.  
  31269.  See Also
  31270.  
  31271.  DosQFSAttach
  31272.  
  31273.  
  31274.  █    GEA
  31275.  ────────────────────────────────────────────────────────────────────────────
  31276.  
  31277.  
  31278.  typedef struct _GEA {    /* gea */
  31279.      BYTE cbName;
  31280.      CHAR szName[1];
  31281.  } GEA;
  31282.  
  31283.  
  31284.  The GEA structure contains an extended-attribute name.
  31285.  
  31286.  
  31287.  Fields
  31288.  
  31289.  cbName  Specifies the length of the extended-attribute name contained in the
  31290.  szName field, not including the null terminating character.
  31291.  
  31292.  szName[1]  Contains the extended-attribute name.
  31293.  
  31294.  
  31295.  See Also
  31296.  
  31297.  EAOP, FEA, GEALIST
  31298.  
  31299.  
  31300.  █    GEALIST
  31301.  ────────────────────────────────────────────────────────────────────────────
  31302.  
  31303.  
  31304.  typedef struct _GEALIST {    /* geal */
  31305.      ULONG cbList;
  31306.      GEA   list[1];
  31307.  } GEALIST;
  31308.  
  31309.  
  31310.  The GEALIST structure contains one or more extended-attribute names.
  31311.  
  31312.  
  31313.  Fields
  31314.  
  31315.  cbList  Specifies the size (in bytes) of the structure.
  31316.  
  31317.  list[1]  Contains an array of one or more GEA structures.
  31318.  
  31319.  
  31320.  Comments
  31321.  
  31322.  The GEALIST structure contains a list of extended-attribute names to
  31323.  retrieve information for. The FEALIST structure contains a list of extended
  31324.  attributes that were found.
  31325.  
  31326.  
  31327.  See Also
  31328.  
  31329.  DosFindFirst2, DosMkDir2, DosOpen2, DosQPathInfo, DosSetFileInfo,
  31330.  DosSetPathInfo, EAOP, FEALIST, GEA
  31331.  
  31332.  
  31333.  █    HCINFO
  31334.  ────────────────────────────────────────────────────────────────────────────
  31335.  
  31336.  
  31337.  typedef struct _HCINFO {    /* hci */
  31338.      CHAR   szFormname[32];
  31339.      LONG   cx;
  31340.      LONG   cy;
  31341.      LONG   xLeftClip;
  31342.      LONG   yBottomClip;
  31343.      LONG   xRightClip;
  31344.      LONG   yTopClip;
  31345.      LONG   xPels;
  31346.      LONG   yPels;
  31347.      LONG   flAttributes;
  31348.  } HCINFO;
  31349.  
  31350.  
  31351.  The HCINFO structure contains information about the hard-copy capabilities
  31352.  of a device.
  31353.  
  31354.  
  31355.  Fields
  31356.  
  31357.  szFormname[32]  Specifies the form name.
  31358.  
  31359.  cx  Specifies the form width (in millimeters).
  31360.  
  31361.  cy  Specifies the form height (top to bottom, in millimeters).
  31362.  
  31363.  xLeftClip  Specifies the left clip limit (in millimeters).
  31364.  
  31365.  yBottomClip  Specifies the bottom clip limit (in millimeters).
  31366.  
  31367.  xRightClip  Specifies the right clip limit (in millimeters).
  31368.  
  31369.  yTopClip  Specifies the top clip limit (in millimeters).
  31370.  
  31371.  xPels  Specifies the number of pels between the left and right clip limits.
  31372.  
  31373.  yPels  Specifies the number of pels between the top and bottom clip limits.
  31374.  
  31375.  flAttributes  Specifies whether the given form is the selected form. This
  31376.  field is HCAPS_CURRENT if the form is selected. Otherwise, it is zero.
  31377.  
  31378.  
  31379.  See Also
  31380.  
  31381.  DevQueryHardcopyCaps
  31382.  
  31383.  
  31384.  Corrections
  31385.  
  31386.  The flAttributes field is set to HCAPS_CURRENT when the specified form is
  31387.  the selected form.
  31388.  
  31389.  
  31390.  █    HELPINIT
  31391.  ────────────────────────────────────────────────────────────────────────────
  31392.  
  31393.  
  31394.  typedef struct _HELPINIT {    /* hinit */
  31395.      USHORT     cb;
  31396.      ULONG      ulReturnCode;
  31397.      PSZ        pszTutorialName;
  31398.      PHELPTABLE phtHelpTable;
  31399.      HMODULE    hmodHelpTableModule;
  31400.      HMODULE    hmodAccelActionBarModule;
  31401.      USHORT     idAccelTable;
  31402.      USHORT     idActionBar;
  31403.      PSZ        pszHelpWindowTitle;
  31404.      USHORT     usShowPanelId;
  31405.      PSZ        pszHelpLibraryName;
  31406.  } HELPINIT;
  31407.  
  31408.  
  31409.  
  31410.  
  31411.  The HELPINIT structure is used when creating a help instance for an
  31412.  application.
  31413.  
  31414.  
  31415.  Fields
  31416.  
  31417.  cb  Specifies the number of bytes in the initialization structure.
  31418.  
  31419.  ulReturnCode  Specifies the value returned by the system at initialization.
  31420.  A value of zero means that initialization was successful.
  31421.  
  31422.  pszTutorialName  Points to the string that contains the default tutorial
  31423.  name. If this field is NULL, the application does not have a tutorial or the
  31424.  tutorial name is specified in each help library.
  31425.  
  31426.  phtHelpTable  Points to the help table or to the resource ID of the help
  31427.  table. If you defined the table in a resource file, the low word should
  31428.  contain the resource ID of the table and the high word must be 0xFFFF.
  31429.  
  31430.  hmodHelpTableModule  Identifies the module handle returned by the
  31431.  DosLoadModule function when the application loaded the resource file. A
  31432.  value of NULL indicates that the resource file containing the help table was
  31433.  appended to the application's executable (.exe) file.
  31434.  
  31435.  hmodAccelActionBarModule  Identifies the handle of the dynamic-link library
  31436.  module that contains the accelerator table and menu-bar template used by a
  31437.  help window. A value of NULL causes the idAccelTable and idActionBar fields
  31438.  to be ignored and the default resources to be used.
  31439.  
  31440.  idAccelTable  Identifies the accelerator table. The accelerator table is
  31441.  found in the dynamic-link library identified by the hmodAccelActionBarModule
  31442.  field. If the default accelerator table is to be used, this field should be
  31443.  NULL.
  31444.  
  31445.  idActionBar  Identifies the menu-bar template used by a help window. The
  31446.  menu-bar template is found in the dynamic-link library identified by the
  31447.  hmodAccelActionBarModule field. If the default menu bar is to be used, this
  31448.  field should be NULL.
  31449.  
  31450.  pszHelpWindowTitle  Points to the string that contains the window title of
  31451.  the help window.
  31452.  
  31453.  usShowPanelId  Specifies whether to display the window (panel) ID on a help
  31454.  window. If this value is CMIC_HIDE_PANEL_ID, the window ID is not shown; if
  31455.  this value is CMIC_SHOW_PANEL_ID, the window ID is shown.
  31456.  
  31457.  pszHelpLibraryName  Points to the string that contains the name of the help
  31458.  library that the system searches on each help request.
  31459.  
  31460.  
  31461.  See Also
  31462.  
  31463.  WinCreateHelpInstance, HELPTABLE
  31464.  
  31465.  
  31466.  █    HELPTABLE
  31467.  ────────────────────────────────────────────────────────────────────────────
  31468.  
  31469.  
  31470.  typedef struct _HELPTABLE {     /* ht */
  31471.      USHORT        idAppWindow;
  31472.      PHELPSUBTABLE phstHelpSubTable;
  31473.      USHORT        idExtPanel;
  31474.  } HELPTABLE;
  31475.  
  31476.  
  31477.  The HELPTABLE structure identifies the help table for a specified
  31478.  application.
  31479.  
  31480.  
  31481.  Fields
  31482.  
  31483.  idAppWindow  Specifies the window ID of a frame or dialog window.
  31484.  
  31485.  phstHelpSubTable  Points to a help subtable. The help subtable contains help
  31486.  panel IDs for the child windows and/or menus in the specified window.
  31487.  
  31488.  idExtPanel  Specifies an extended help panel ID. This help panel is
  31489.  displayed whenever extended help for the specified window is requested.
  31490.  
  31491.  
  31492.  Comments
  31493.  
  31494.  The help table for an application usually consists of an array of two or
  31495.  more HELPTABLE structures. Each structure specifies one window, such as a
  31496.  frame or dialog window, and points to one subtable containing the help panel
  31497.  IDs for each item in the window that the user may request help for. To mark
  31498.  the end of the array, the last structure in the array must be zero-filled.
  31499.  
  31500.  The help subtable, pointed to by the phstHelpSubTable field, is an array of
  31501.  help panel IDs and window or menu IDs. The first element in the help
  31502.  subtable, a 16-bit integer, specifies the size, in 16-bit words, of each
  31503.  subsequent element. The system requires that the first element be at least
  31504.  2. All subsequent elements consist of the number of words specified by the
  31505.  first element. The first word in an element must be a window or menu ID. The
  31506.  second word must be a help panel ID. Any additional words are not used by
  31507.  the system. The last element in the help subtable must be zero-filled.
  31508.  
  31509.  
  31510.  See Also
  31511.  
  31512.  HM_CREATE_HELP_TABLE
  31513.  
  31514.  
  31515.  █    KBDHWID
  31516.  ────────────────────────────────────────────────────────────────────────────
  31517.  
  31518.  
  31519.  typedef struct _KBDHWID {    /* kbhw */
  31520.      USHORT cb;
  31521.      USHORT idKbd;
  31522.      USHORT usReserved1;
  31523.      USHORT usReserved2;
  31524.  } KBDHWID;
  31525.  
  31526.  
  31527.  The KBDHWID structure contains information that identifies keyboard
  31528.  hardware.
  31529.  
  31530.  
  31531.  Fields
  31532.  
  31533.  cb  Specifies the size of the structure (in bytes). Programs written in the
  31534.  C language should use the sizeof operator to set this field.
  31535.  
  31536.  idKbd  Specifies the ID number generated by the keyboard hardware. This
  31537.  field can be one of the following values:
  31538.  
  31539.  Keyboard                          Value
  31540.  ────────────────────────────────────────────────────────────────────────────
  31541.  
  31542.  KEYBOARD_AT_COMPATABLE            IBM PC/AT or compatible keyboard
  31543.  
  31544.  KEYBOARD_ENHANCED_101             101-key enhanced keyboard
  31545.  
  31546.  KEYBOARD_ENHANCED_102             102-key enhanced keyboard
  31547.  
  31548.  KEYBOARD_ENHANCED_122             122-key enhanced keyboard
  31549.  
  31550.  KEYBOARD_SPACESAVER               Space Saver enhanced keyboard
  31551.  
  31552.  
  31553.  
  31554.  usReserved1  Specifies a reserved value.
  31555.  
  31556.  usReserved2  Specifies a reserved value.
  31557.  
  31558.  
  31559.  See Also
  31560.  
  31561.  KbdGetHWID
  31562.  
  31563.  
  31564.  █    KBDINFO
  31565.  ────────────────────────────────────────────────────────────────────────────
  31566.  
  31567.  
  31568.  typedef struct _KBDINFO {    /* kbst */
  31569.      USHORT cb;
  31570.      USHORT fsMask;
  31571.      USHORT chTurnAround;
  31572.      USHORT fsInterim;
  31573.      USHORT fsState;
  31574.  } KBDINFO;
  31575.  
  31576.  
  31577.  The KBDINFO structure contains status information for a logical keyboard.
  31578.  
  31579.  
  31580.  Fields
  31581.  
  31582.  cb  Specifies the size of the structure (in bytes). Programs written in the
  31583.  C language should use the sizeof operator to set this field.
  31584.  
  31585.  fsMask  Specifies the current keyboard modes. It can be a combination of the
  31586.  following values:
  31587.  
  31588.  Value                             Meaning
  31589.  ────────────────────────────────────────────────────────────────────────────
  31590.  
  31591.  KEYBOARD_ECHO_ON                  Echo mode turned on.
  31592.  
  31593.  KEYBOARD_ECHO_OFF                 Echo mode turned off.
  31594.  
  31595.  KEYBOARD_BINARY_MODE              Binary mode turned on.
  31596.  
  31597.  KEYBOARD_ASCII_MODE               ASCII mode turned on.
  31598.  
  31599.  KEYBOARD_MODIFY_STATE             The fsState field is to be modified.
  31600.                                    Applies to the KbdSetStatus function
  31601.                                    only.
  31602.  
  31603.  KEYBOARD_MODIFY_INTERIM           The fsInterim field is to be modified.
  31604.                                    Applies to the KbdSetStatus function
  31605.                                    only.
  31606.  
  31607.  KEYBOARD_MODIFY_TURNAROUND        The chTurnAround field is to be modified.
  31608.                                    Applies to the KbdSetStatus function
  31609.                                    only.
  31610.  
  31611.  KEYBOARD_2B_TURNAROUND            Two-byte turn-around character. If not
  31612.                                    given, the turn-around character is one
  31613.                                    byte.
  31614.  
  31615.  KEYBOARD_SHIFT_REPORT             Shift reporting turned on.
  31616.  
  31617.  
  31618.  
  31619.  Note that echo mode is either turned on or off. Only one input mode, binary
  31620.  or ASCII, can be turned on at any given time.
  31621.  
  31622.  chTurnAround  Specifies the turn-around character. If this value includes
  31623.  0x0080, the character is two-bytes packed in the low and high bytes of this
  31624.  field. Otherwise, the character is a single byte in the low byte.
  31625.  
  31626.  fsInterim  Specifies the interim character flags. If this field is 0x0020,
  31627.  the program has requested character conversion. If it is 0x0080, the interim
  31628.  character flag is on.
  31629.  
  31630.  fsState  Specifies the state of the shift keys. It can be any combination of
  31631.  the following values:
  31632.  
  31633.  Value                             Meaning
  31634.  ────────────────────────────────────────────────────────────────────────────
  31635.  
  31636.  KBDSTF_RIGHTSHIFT                 Right SHIFT key down.
  31637.  
  31638.  KBDSTF_LEFTSHIFT                  Left SHIFT key down.
  31639.  
  31640.  KBDSTF_CONTROL                    CTRL key down.
  31641.  
  31642.  KBDSTF_ALT                        ALT key down.
  31643.  
  31644.  KBDSTF_SCROLLLOCK_ON              SCROLL LOCK mode turned on.
  31645.  
  31646.  KBDSTF_NUMLOCK_ON                 NUMLOCK mode turned on.
  31647.  
  31648.  KBDSTF_CAPSLOCK_ON                CAPSLOCK mode turned on.
  31649.  
  31650.  KBDSTF_INSERT_ON                  INS mode turned on.
  31651.  
  31652.  
  31653.  
  31654.  See Also
  31655.  
  31656.  KbdGetStatus, KbdSetStatus
  31657.  
  31658.  
  31659.  Changes
  31660.  
  31661.  The constants for the fsState field are now preceded with KBDSTF_.
  31662.  
  31663.  
  31664.  █    KBDKEYINFO
  31665.  ────────────────────────────────────────────────────────────────────────────
  31666.  
  31667.  
  31668.  typedef struct _KBDKEYINFO {    /* kbci */
  31669.      UCHAR  chChar;
  31670.      UCHAR  chScan;
  31671.      UCHAR  fbStatus;
  31672.      UCHAR  bNlsShift;
  31673.      USHORT fsState;
  31674.      ULONG  time;
  31675.  } KBDKEYINFO;
  31676.  
  31677.  
  31678.  The KBDKEYINFO structure contains information about the last key pressed.
  31679.  
  31680.  
  31681.  Fields
  31682.  
  31683.  chChar  Specifies the character derived from translation of the chScan
  31684.  field.
  31685.  
  31686.  chScan  Specifies the scan code received from the keyboard, identifying the
  31687.  key pressed. This scan code may be modified during the translation process.
  31688.  
  31689.  fbStatus  Specifies the state of the retrieved scan code. It can be any
  31690.  combination of the following values:
  31691.  
  31692.  Value                             Meaning
  31693.  ────────────────────────────────────────────────────────────────────────────
  31694.  
  31695.  KBDTRF_SHIFT_KEY_IN               Shift key is received (valid only in
  31696.                                    binary mode when shift reporting is
  31697.                                    turned on).
  31698.  
  31699.  KBDTRF_CONVERSION_REQUEST         Conversion requested.
  31700.  
  31701.  KBDTRF_FINAL_CHAR_IN              Final character received.
  31702.  
  31703.  KBDTRF_INTERIM_CHAR_IN            Interim character received.
  31704.  
  31705.  KBDTRF_EXTENDED_CODE              The scan code is an extended code, not a
  31706.                                    character. .
  31707.  
  31708.  
  31709.  
  31710.  bNlsShift  Specifies a reserved value; must be zero.
  31711.  
  31712.  fsState  Specifies the state of the shift keys. It can be any combination of
  31713.  the following values:
  31714.  
  31715.  Value                             Meaning
  31716.  ────────────────────────────────────────────────────────────────────────────
  31717.  
  31718.  KBDSTF_RIGHTSHIFT                 Right SHIFT key down.
  31719.  
  31720.  KBDSTF_LEFTSHIFT                  Left SHIFT key down.
  31721.  
  31722.  KBDSTF_CONTROL                    Either CTRL key down.
  31723.  
  31724.  KBDSTF_ALT                        Either ALT key down.
  31725.  
  31726.  KBDSTF_SCROLLLOCK_ON              SCROLL LOCK mode turned on.
  31727.  
  31728.  KBDSTF_NUMLOCK_ON                 NUMLOCK mode turned on.
  31729.  
  31730.  KBDSTF_CAPSLOCK_ON                CAPSLOCK mode turned on.
  31731.  
  31732.  KBDSTF_INSERT_ON                  INS key turned on.
  31733.  
  31734.  KBDSTF_LEFTCONTROL                Left CTRL key down.
  31735.  
  31736.  KBDSTF_LEFTALT                    Left ALT key down.
  31737.  
  31738.  KBDSTF_RIGHTCONTROL               Right CTRL key down.
  31739.  
  31740.  KBDSTF_RIGHTALT                   Right ALT key down.
  31741.  
  31742.  KBDSTF_SCROLLLOCK                 SCROLL LOCK key down.
  31743.  
  31744.  KBDSTF_NUMLOCK                    NUMLOCK key down.
  31745.  
  31746.  KBDSTF_CAPSLOCK                   CAPSLOCK key down.
  31747.  
  31748.  KBDSTF_SYSREQ                     SYSREQ key down.
  31749.  
  31750.  
  31751.  
  31752.  time  Specifies the time stamp of the keystroke (in milliseconds).
  31753.  
  31754.  
  31755.  See Also
  31756.  
  31757.  KbdCharIn, KbdPeek, KBD_PEEKCHAR
  31758.  
  31759.  
  31760.  Changes
  31761.  
  31762.  KBDTRF_EXTENDED_CODE is a possible value for the fsStatus field and
  31763.  indicates that the scan code is an extended code, not a character.
  31764.  
  31765.  The constants for the fbStatus field are now preceded with KBDTRF_. The
  31766.  constants for the fsState field are now preceded with KBDSTF_.
  31767.  
  31768.  
  31769.  █    KBDTRANS
  31770.  ────────────────────────────────────────────────────────────────────────────
  31771.  
  31772.  
  31773.  typedef struct _KBDTRANS {    /* kbxl */
  31774.      UCHAR  chChar;
  31775.      UCHAR  chScan;
  31776.      UCHAR  fbStatus;
  31777.      UCHAR  bNlsShift;
  31778.      USHORT fsState;
  31779.      ULONG  time;
  31780.      USHORT fsDD;
  31781.      USHORT fsXlate;
  31782.      USHORT fsShift;
  31783.      USHORT sZero;
  31784.  } KBDTRANS;
  31785.  
  31786.  
  31787.  The KBDTRANS structure contains translated character information.
  31788.  
  31789.  
  31790.  Fields
  31791.  
  31792.  chChar  Specifies the character value of the translated scan code. The
  31793.  function copies the value to this field before returning.
  31794.  
  31795.  chScan  Specifies the scan code of the keystroke to be translated. This
  31796.  field must be set before the function is called.
  31797.  
  31798.  fbStatus  Specifies the state of the returned scan code. It can be any
  31799.  combination of the following values:
  31800.  
  31801.  Value                             Meaning
  31802.  ────────────────────────────────────────────────────────────────────────────
  31803.  
  31804.  KBDTRF_SHIFT_KEY_IN               Shift key received (valid only in binary
  31805.                                    mode when shift reporting is turned on).
  31806.  
  31807.  KBDTRF_CONVERSION_REQUEST         Conversion requested.
  31808.  
  31809.  KBDTRF_FINAL_CHAR_IN              Final character received.
  31810.  
  31811.  KBDTRF_INTERIM_CHAR_IN            Interim character received.
  31812.  
  31813.  
  31814.  
  31815.  bNlsShift  Specifies a reserved value; must be zero.
  31816.  
  31817.  fsState  Specifies the state of the shift keys. It can be one of the
  31818.  following values:
  31819.  
  31820.  Value                             Meaning
  31821.  ────────────────────────────────────────────────────────────────────────────
  31822.  
  31823.  KBDSTF_RIGHTSHIFT                 Right SHIFT key down.
  31824.  
  31825.  KBDSTF_LEFTSHIFT                  Left SHIFT key down.
  31826.  
  31827.  KBDSTF_CONTROL                    Either CTRL key down.
  31828.  
  31829.  KBDSTF_ALT                        Either ALT key down.
  31830.  
  31831.  KBDSTF_SCROLLLOCK_ON              SCROLL LOCK mode turned on.
  31832.  
  31833.  KBDSTF_NUMLOCK_ON                 NUMLOCK mode turned on.
  31834.  
  31835.  KBDSTF_CAPSLOCK_ON                CAPSLOCK mode turned on.
  31836.  
  31837.  KBDSTF_INSERT_ON                  INS mode turned on.
  31838.  
  31839.  KBDSTF_LEFTCONTROL                Left CTRL key down.
  31840.  
  31841.  KBDSTF_LEFTALT                    Left ALT key down.
  31842.  
  31843.  KBDSTF_RIGHTCONTROL               Right CTRL key down.
  31844.  
  31845.  KBDSTF_RIGHTALT                   Right ALT key down.
  31846.  
  31847.  KBDSTF_SCROLLLOCK                 SCROLL LOCK key down.
  31848.  
  31849.  KBDSTF_NUMLOCK                    NUMLOCK key down.
  31850.  
  31851.  KBDSTF_CAPSLOCK                   CAPSLOCK key down.
  31852.  
  31853.  KBDSTF_SYSREQ                     SYSREQ key down.
  31854.  
  31855.  
  31856.  
  31857.  time  Specifies the time stamp of the keystroke (in milliseconds).
  31858.  
  31859.  fsDD  Defined for monitor packets. For more information, see the DosMonReg
  31860.  function.
  31861.  
  31862.  fsXlate  Specifies the translation flags. If this field is 0x0000,
  31863.  translation is incomplete. If it is 0x0001, translation is complete.
  31864.  
  31865.  fsShift  Specifies the state of translation across successive calls.
  31866.  Initially, this field should be zero. It should be reset to zero when the
  31867.  caller wants to start a new translation. Note that it may take several calls
  31868.  to the KbdXlate function to complete a character, so this field should not
  31869.  be changed unless a new translation is desired. This field is cleared when
  31870.  translation is complete.
  31871.  
  31872.  sZero  Specifies a reserved value; must be zero.
  31873.  
  31874.  
  31875.  See Also
  31876.  
  31877.  DosMonReg, KbdXlate
  31878.  
  31879.  
  31880.  Changes
  31881.  
  31882.  The constants for the fbStatus field are now preceded with KBDTRF_. The
  31883.  constants for the fsState field are now preceded with KBDSTF_.
  31884.  
  31885.  
  31886.  █    LDTADDRINFO
  31887.  ────────────────────────────────────────────────────────────────────────────
  31888.  
  31889.  
  31890.  typedef struct _LDTADDRINFO {    /* ldtaddr */
  31891.      PULONG  pulPhysAddr;
  31892.      USHORT  cb;
  31893.  } LDTADDRINFO;
  31894.  
  31895.  
  31896.  The LDTADDRINFO structure holds information about an address to be added to
  31897.  the local descriptor table (LDT).
  31898.  
  31899.  
  31900.  Fields
  31901.  
  31902.  pulPhysAddr  Points to the 32-bit physical address of the beginning of the
  31903.  block of memory for which an LDT selector is requested.
  31904.  
  31905.  cb  Specifies the number of bytes for the requested memory.
  31906.  
  31907.  
  31908.  See Also
  31909.  
  31910.  SCR_ALLOCLDT, SCR_ALLOCLDTOFF
  31911.  
  31912.  
  31913.  █    LINFOSEG
  31914.  ────────────────────────────────────────────────────────────────────────────
  31915.  
  31916.  
  31917.  typedef struct _LINFOSEG {    /* lis */
  31918.      PID     pidCurrent;
  31919.      PID     pidParent;
  31920.      USHORT  prtyCurrent;
  31921.      TID     tidCurrent;
  31922.      USHORT  sgCurrent;
  31923.      UCHAR   rfProcStatus;
  31924.      UCHAR   dummy1;
  31925.      BOOL    fForeground;
  31926.      UCHAR   typeProcess;
  31927.      UCHAR   dummy2;
  31928.      SEL     selEnvironment;
  31929.      USHORT  offCmdLine;
  31930.      USHORT  cbDataSegment;
  31931.      USHORT  cbStack;
  31932.      USHORT  cbHeap;
  31933.      HMODULE hmod;
  31934.      SEL     selDS;
  31935.  } LINFOSEG;
  31936.  
  31937.  
  31938.  The LINFOSEG structure contains information local to the current process.
  31939.  
  31940.  
  31941.  Fields
  31942.  
  31943.  pidCurrent  Specifies the identifier of the current process.
  31944.  
  31945.  pidParent  Specifies the identifier of the parent process.
  31946.  
  31947.  prtyCurrent  Specifies the priority of the current thread.
  31948.  
  31949.  tidCurrent  Specifies the identifier of the current thread.
  31950.  
  31951.  sgCurrent  Specifies the current screen group.
  31952.  
  31953.  rfProcStatus  Specifies the process status. A value of PS_EXITLIST indicates
  31954.  the process is in an exit-list routine.
  31955.  
  31956.  dummy1  Reserved.
  31957.  
  31958.  fForeground  Specifies that the current process is in foreground.
  31959.  
  31960.  typeProcess  Specifies the process type. It can be one of the following
  31961.  values:
  31962.  
  31963.  Value                             Meaning
  31964.  ────────────────────────────────────────────────────────────────────────────
  31965.  
  31966.  PT_DETACHED                       Process is running as a detached process.
  31967.  
  31968.  PT_FULLSCREEN                     Process is running in a full-screen
  31969.                                    protected-mode session.
  31970.  
  31971.  PT_PM                             Process is running in the Presentation
  31972.                                    Manager screen group.
  31973.  
  31974.  PT_REALMODE                       Process is running in DOS-compatibility
  31975.                                    mode.
  31976.  
  31977.  PT_WINDOWABLEVIO                  Process is running in a VIO-window
  31978.                                    session.
  31979.  
  31980.  
  31981.  
  31982.  dummy2  Reserved.
  31983.  
  31984.  selEnvironment  Specifies the selector to the application's copy of the
  31985.  environment.
  31986.  
  31987.  offCmdLine  Specifies the offset to the environment where the command line
  31988.  that is used to run the current application is copied.
  31989.  
  31990.  cbDataSegment  Specifies the size of the default data segment.
  31991.  
  31992.  cbStack  Specifies the size of the stack.
  31993.  
  31994.  cbHeap  Specifies the size of the heap.
  31995.  
  31996.  hmod  Identifies the program.
  31997.  
  31998.  selDS  Specifies the default data segment.
  31999.  
  32000.  
  32001.  Comments
  32002.  
  32003.  The following fields are contained in registers at start-up:
  32004.  
  32005.  Field                             Register
  32006.  ────────────────────────────────────────────────────────────────────────────
  32007.  
  32008.  SelEnvironment                    ax
  32009.  
  32010.  offCmdLine                        bx
  32011.  
  32012.  cbDataSegment                     cx
  32013.  
  32014.  cbStack                           dx
  32015.  
  32016.  cbHeap                            si
  32017.  
  32018.  hmod                              di
  32019.  
  32020.  selDS                             ds
  32021.  
  32022.  
  32023.  
  32024.  See Also
  32025.  
  32026.  DosGetInfoSeg, GINFOSEG
  32027.  
  32028.  
  32029.  Changes
  32030.  
  32031.  The PT_FULLSCREEN, PT_REALMODE, PT_WINDOWABLEVIO, PT_PM, and PT_DETACHED
  32032.  constants replace the numeric values previously defined for the typeProcess
  32033.  field. The constant PS_EXITLIST is a valid value for the rfProcStatus field.
  32034.  
  32035.  
  32036.  
  32037.  Corrections
  32038.  
  32039.  The rfProcStatus field specifies the process status, not the subscreen
  32040.  group.
  32041.  
  32042.  
  32043.  █    MATRIXLF
  32044.  ────────────────────────────────────────────────────────────────────────────
  32045.  
  32046.  
  32047.  typedef struct _MATRIXLF {    /* matlf */
  32048.      FIXED fxM11;
  32049.      FIXED fxM12;
  32050.      LONG  lM13;
  32051.      FIXED fxM21;
  32052.      FIXED fxM22;
  32053.      LONG  lM23;
  32054.      LONG  lM31;
  32055.      LONG  lM32;
  32056.      LONG  lM33;
  32057.  } MATRIXLF;
  32058.  
  32059.  
  32060.  The MATRIXLF structure contains the scaling, translation, rotation, shear,
  32061.  and reflection transformation values that MS OS/2 uses when your application
  32062.  calls one of the transformation functions.
  32063.  
  32064.  If the matrix contains scaling values, the following fields are set:
  32065.  
  32066.  Field                             Description
  32067.  ────────────────────────────────────────────────────────────────────────────
  32068.  
  32069.  fxM11                             Specifies the horizontal scaling value.
  32070.  
  32071.  fxM22                             Specifies the vertical scaling value.
  32072.  
  32073.  
  32074.  
  32075.  If the matrix contains translation values, the following fields are set:
  32076.  
  32077.  Field                             Description
  32078.  ────────────────────────────────────────────────────────────────────────────
  32079.  
  32080.  lM31                              Specifies the horizontal translation
  32081.                                    value.
  32082.  
  32083.  lM32                              Specifies the vertical translation value.
  32084.  
  32085.  
  32086.  
  32087.  If the matrix contains rotation values, the following fields are set:
  32088.  
  32089.  Field                             Description
  32090.  ────────────────────────────────────────────────────────────────────────────
  32091.  
  32092.  fxM11                             Specifies the cosine of the angle of
  32093.                                    rotation.
  32094.  
  32095.  fxM12                             Specifies the negative sine of the angle
  32096.                                    of rotation.
  32097.  
  32098.  fxM21                             Specifies the sine of the angle of
  32099.                                    rotation.
  32100.  
  32101.  fxM22                             Specifies the cosine of the angle of
  32102.                                    rotation.
  32103.  
  32104.  
  32105.  
  32106.  If the matrix contains vertical-shear values, the following fields are set:
  32107.  
  32108.  Field                             Description
  32109.  ────────────────────────────────────────────────────────────────────────────
  32110.  
  32111.  fxM21                             Specifies the horizontal shear value.
  32112.  
  32113.  fxM22                             Specifies the vertical shear value.
  32114.  
  32115.  
  32116.  
  32117.  If the matrix contains horizontal-shear values, the following fields are
  32118.  set:
  32119.  
  32120.  Field                             Description
  32121.  ────────────────────────────────────────────────────────────────────────────
  32122.  
  32123.  fxM11                             Specifies the horizontal-shear value.
  32124.  
  32125.  fxM12                             Specifies the vertical-shear value.
  32126.  
  32127.  
  32128.  
  32129.  If the matrix contains reflection values, the following fields are set:
  32130.  
  32131.  Field                             Description
  32132.  ────────────────────────────────────────────────────────────────────────────
  32133.  
  32134.  fxM11                             Specifies the vertical-reflection value.
  32135.                                    (This value is always negative. It
  32136.                                    causes reflection about the x-axis.)
  32137.  
  32138.  fxM22                             Specifies the horizontal-reflection
  32139.                                    value. (This value is always negative.
  32140.                                    It causes reflection about the y-axis.)
  32141.  
  32142.  
  32143.  
  32144.  See Also
  32145.  
  32146.  GpiCallSegmentMatrix, GpiQueryDefaultViewMatrix,
  32147.  GpiQueryModelTransformMatrix, GpiQuerySegmentTransformMatrix,
  32148.  GpiQueryViewingTransformMatrix, GpiSetDefaultViewMatrix,
  32149.  GpiSe