home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 10 Tools / 10-Tools.zip / smart21b.zip / SM_PROG2.INF (.txt) < prev    next >
OS/2 Help File  |  1995-09-15  |  106KB  |  3,542 lines
  1.  
  2. ΓòÉΓòÉΓòÉ 1. The SMART Programming Guide ΓòÉΓòÉΓòÉ
  3.  
  4.    The SMART Programming Guide
  5.       UDMD and MiCL
  6.        Version 2.1B
  7.       September 1995
  8.  
  9.    (C) 1991, 1994, 1995 One Up Corporation
  10.      All Rights Reserved
  11.  
  12.        Notice 
  13.        Table of Contents 
  14.  
  15.  
  16. ΓòÉΓòÉΓòÉ 2. Notice ΓòÉΓòÉΓòÉ
  17.  
  18. ** NOTICE ** 
  19.  
  20. This document may not, in whole or in part, be copied, reproduced, photocopied, 
  21. translated, or reproduced to any electronic medium or machine readable form 
  22. without prior written consent from One Up Corporation. 
  23.  
  24. This publication could contain technical inaccuracies or typographical errors. 
  25. As changes are periodically made to the information herein; these changes may 
  26. be incorporated in new additions of the publication. One Up Corporation may 
  27. make improvements and/or changes in the product and/or the program described in 
  28. this publication at any time. 
  29.  
  30. One Up Corporation is not responsible for any direct or indirect damage or loss 
  31. of business resulting from inaccuracies or omissions in this publication.  The 
  32. specifications contained in this document are subject to change without notice. 
  33.  
  34. SMART - Source Migration Analysis Reporting Toolset is a trademark of One Up 
  35. Corporation. OS/2, Presentation Manager are trademarks of the International 
  36. Business Machines Corporation. IBM is a registered trademark of the 
  37. International Business Machines Corporation. Other trademarks are property of 
  38. their respective companies. 
  39.  
  40.       CONTENTS 
  41.  
  42.  
  43. ΓòÉΓòÉΓòÉ 3. Table of Contents ΓòÉΓòÉΓòÉ
  44.  
  45.        Section 1 - UDMD Programming 
  46.         Introduction 
  47.         Format Tags 
  48.          .Notice 
  49.          .Table 
  50.          .Version 
  51.          .Date 
  52.          .Keyword 
  53.          .SComment 
  54.          .LComment 
  55.          .Sample 
  56.          .Prototyp 
  57.          .Template 
  58.          .Refer 
  59.          .Command 
  60.          .Notes 
  61.         Programming Notes 
  62.        Section 2 - MiCL Programming 
  63.         Introduction 
  64.         General Language Description 
  65.         Variables and Constants 
  66.         Strings and Quotations 
  67.         SMART Built-in Functions 
  68.          SmDisplayDlg( ) 
  69.          SmGetListName( ) 
  70.          SmGetListPath( ) 
  71.          SmGetSmartPath( ) 
  72.          SmIgnoreKeyword( ) 
  73.          SmListDlg( ) 
  74.          SmLoadVars( ) 
  75.          SmMigrateKeyword( ) 
  76.          SmNoComment( ) 
  77.          SmNoMigrate( ) 
  78.          SmOutputLine( ) 
  79.          SmOutputNote( ) 
  80.          SmPromptDlg( ) 
  81.          SmRemove( ) 
  82.          SmSaveVars( ) 
  83.          SmSendToEditor( ) 
  84.         MiCL Instructions 
  85.         Event Command Procedures 
  86.         Programming Notes and Tips 
  87.          MiCL Basics 
  88.          Preset Variables 
  89.          Two MiCL Examples 
  90.          Pre and Post Command Sets 
  91.          Use of Templates 
  92.          Use of Dialog Functions 
  93.          Migration Control 
  94.          Migration Notes and Comments 
  95.          Global, Static and Local Variables 
  96.          String and Variable Evaluation 
  97.          Launching the Editor 
  98.          Testing MiCL Command Sets 
  99.        Reference 
  100.         Reserved Words 
  101.         Keyword Identifier Codes 
  102.  
  103.  Navigation Links 
  104.  
  105.       CONTINUE - Section 1 
  106.  
  107.  
  108. ΓòÉΓòÉΓòÉ 4. Section 1 - UDMD Programming ΓòÉΓòÉΓòÉ
  109.  
  110. User Defined Migration Database programming 
  111.  
  112.         Introduction 
  113.         Format Tags 
  114.         Programming Notes 
  115.  
  116.  Navigation Links 
  117.  
  118.       CONTINUE - Introduction 
  119.       BACK - Table of Contents 
  120.  
  121.  
  122. ΓòÉΓòÉΓòÉ 4.1. UDMD - Introduction ΓòÉΓòÉΓòÉ
  123.  
  124. UDMD - Introduction 
  125.  
  126.   Introduction - Programming a User Defined Migration Data Base 
  127.  
  128.   Input for the creation of User Databases (UDMD) is an ASCII text file 
  129. containing format tags and data. One database at a time can be used in 
  130. conjunction with a SMART Migration Database for analysis and Migration of 
  131. program source code.  The User Migration Dictionary (text File) is transformed 
  132. into SMART Migration database format and tables using the utility function 
  133. under "Tables", "Create User UDMD"  under the main menu of SMART. 
  134.  
  135.   A sample of this input text file follows: 
  136.  
  137.    .Notice  =Copyright (c) 1993 One Up Corporation, All Rights Reserved
  138.    .Table  =OS/2 1.3 to OS/2 2.1
  139.    .Version =1.0
  140.    .Date   =11-03-93
  141.  
  142.    .Keyword =010 020 130 DosFindFirst2
  143.    .SComment=Parameters changed to ULONG and return structure changed
  144.    .LComment=Parameters changed to ULONG values.  Note that the variable
  145.         =to receive the number of matching entries (addressed by the
  146.         =6th parameter) has been changed to a ULONG value.
  147.         =DosFindFirst now includes additional attribute flags.  The
  148.         =previous reserved parameter (last parameter) has been
  149.         =eliminated.  The returned structure for FIL_STANDARD is now
  150.         =FILEFINDBUF3 and for FIL_QUERYEASIZE it is FILEFINDBUF4.
  151.    .Notes  =If all shorts are changed to longs, the last arg is Ok
  152.    .Sample  =OS/2 1.3:
  153.         =  HDIR     hDir   = HDIR_CREATE;
  154.         =  USHORT    usCount = 1;
  155.         =  FILEFINDBUF2 FindBuf;
  156.         =  if (!DosFindFirst2 ("C:\\*.*", &hDir, FILE_NORMAL,
  157.         =     &FindBuf, sizeof(FindBuf), &usCount,
  158.         =:  Note that the last arg is a USHORT
  159.         =     FIL_QUERYEASIZE, 0))
  160.         =  ...
  161.         =OS/2 2.1:
  162.         =  HDIR     hDir   = HDIR_CREATE;
  163.         =  ULONG     ulCount = 1;
  164.         =  FILEFINDBUF4 FindBuf;
  165.         =  if (!DosFindFirst ("C:\\*.*", &hDir, FILE_NORMAL,
  166.         =     &FindBuf, sizeof(FindBuf), &ulCount,
  167.         =     FIL_QUERYEASIZE))
  168.         =  ...
  169.    .Prototyp=APIRET APIENTRY DosFindFirst(PSZ pszFileSpec, PHDIR phdir,
  170.         =  ULONG flAttribute, PVOID pfindbuf, ULONG cbBuf,
  171.         =  PULONG pcFileNames, ULONG ulInfoLevel);
  172.    .Template=DosFindFirst ($P1,$P2,$P3,$P4,$P5,$P6,$P7)
  173.    .Command =/* Evaluate and output template */
  174.         =SmMigrateKeyword($T1)
  175.    .Refer  =DosFindFirst
  176.    .Refer  =FILEFINDBUF3
  177.    .Refer  =FILEFINDBUF4
  178.    .Refer  =$FILEFINDBUF
  179.    .Refer  =$FILEFINDBUF2
  180.  
  181.   You may note that the table code contains a format tag starting with a period 
  182. in column one.  An equal sign appears in column 10 with the data for each 
  183. element beginning in column 11. If a colon is found in column 11 (first data 
  184. column) SMART will ignore the record.  This can be used for internal comments. 
  185. The line will appear in SMART View displays. 
  186.  
  187.   Each input file must contain the table header data at the beginning of the 
  188. file.  Line skips (carriage returns) can be used anywhere in the file to 
  189. improve readability and should most probably be utilized between keyword 
  190. definitions to separate keyword data. 
  191.  
  192. Navigation Links 
  193.  
  194.       CONTINUE - Format Tags 
  195.       BACK - Section 1 - UDMD Programming 
  196.       SECTION 1 - UDMD Programming 
  197.       CONTENTS 
  198.  
  199.  
  200. ΓòÉΓòÉΓòÉ 4.2. UDMD - Format Tags ΓòÉΓòÉΓòÉ
  201.  
  202. UDMD - Format tags 
  203.  
  204.   Format tags are used to identify the coding lines in a Migration table 
  205. dictionary. 
  206.  
  207.   The following tags are available for use in a UDMD. 
  208.  
  209.          .Notice 
  210.          .Table 
  211.          .Version 
  212.          .Date 
  213.          .Keyword 
  214.          .SComment 
  215.          .LComment 
  216.          .Sample 
  217.          .Prototyp 
  218.          .Template 
  219.          .Refer 
  220.          .Command 
  221.          .Notes 
  222.  
  223.  Navigation Links 
  224.  
  225.       CONTINUE - Notice Tag 
  226.       BACK - UDMD - Introduction 
  227.       SECTION 1 - UDMD Programming 
  228.       CONTENTS 
  229.  
  230.  
  231. ΓòÉΓòÉΓòÉ 4.2.1. Notice Tag ΓòÉΓòÉΓòÉ
  232.  
  233. .Notice Tag 
  234.  
  235.   .Notice - (Optional)  (Max. 79 characters) 
  236.  
  237.   Notice is simply a comment line and is not processed by SMART. 
  238.  
  239.   Example: 
  240.  
  241.    .Notice  =Copyright (c) 1993 One Up Corporation, All Rights Reserved
  242.  
  243. Navigation Links 
  244.  
  245.       CONTINUE - Table Tag 
  246.       BACK - Format Tags 
  247.       FORMAT TAGS 
  248.       SECTION 1 - UDMD Programming 
  249.       CONTENTS 
  250.  
  251.  
  252. ΓòÉΓòÉΓòÉ 4.2.2. Table Tag ΓòÉΓòÉΓòÉ
  253.  
  254. .Table Tag 
  255.  
  256.   .Table - (Required - once at beginning of file) (Max 48 characters) 
  257.  
  258.   Table specifies the name of the migration table.  This is used for display 
  259. only in the SMART Tables display panel. 
  260.  
  261.   Example: 
  262.  
  263.    .Table  =OS/2 1.3 to OS/2 2.1
  264.  
  265. Navigation Links 
  266.  
  267.       CONTINUE - Version Tag 
  268.       BACK - Notice Tag 
  269.       FORMAT TAGS 
  270.       SECTION 1 - UDMD Programming 
  271.       CONTENTS 
  272.  
  273.  
  274. ΓòÉΓòÉΓòÉ 4.2.3. Version Tag ΓòÉΓòÉΓòÉ
  275.  
  276. .Version Tag 
  277.  
  278.   .Version - (Required - once at beginning of file) (Max 8 characters) 
  279.  
  280.   Version allows you to specify a version number for the table.  This is used 
  281. for display only in the SMART Tables display panel. 
  282.  
  283.   Example: 
  284.  
  285.    .Version =1.0
  286.  
  287. Navigation Links 
  288.  
  289.       CONTINUE - Date Tag 
  290.       BACK - Table Tag 
  291.       FORMAT TAGS 
  292.       SECTION 1 - UDMD Programming 
  293.       CONTENTS 
  294.  
  295.  
  296. ΓòÉΓòÉΓòÉ 4.2.4. Date Tag ΓòÉΓòÉΓòÉ
  297.  
  298. .Date Tag 
  299.  
  300.   .Date - (Required - once at beginning of file) (Max 8 characters) 
  301.  
  302.   Date allows you to specify a creation or modification date for the table. 
  303. This is used for reference only and appears in the SMART Tables display panel. 
  304.  
  305.   Example: 
  306.  
  307.    .Date   =12-31-99
  308.  
  309. Navigation Links 
  310.  
  311.       CONTINUE - Keyword Tag 
  312.       BACK - Version Tag 
  313.       FORMAT TAGS 
  314.       SECTION 1 - UDMD Programming 
  315.       CONTENTS 
  316.  
  317.  
  318. ΓòÉΓòÉΓòÉ 4.2.5. Keyword Tag ΓòÉΓòÉΓòÉ
  319.  
  320. .Keyword Tag 
  321.  
  322.   .Keyword - (Required at the beginning of a keyword definition data set) 
  323.  
  324.   The Keyword is a composite data statement consisting of four parameters: 
  325.  
  326.          Type Code - 3 characters, column 11-13 
  327.          Category Code - 3 characters, column 15-17 
  328.          Functional Area Code - 3 characters, column 19-21 
  329.          Keyword Name - Column 23 (Max 48 Characters) 
  330.  
  331.    The Type Code, Category Code and Functional Area Code must match the valid 
  332.  codes specified in the companion primary SMART Migration Database. 
  333.  
  334.    All table records up to the next Keyword data tag will be assigned to the 
  335.  keyword defined in this statement. 
  336.  
  337.    Example: 
  338.  
  339.      .Keyword =010 020 130 DosFindFirst2
  340.  
  341.  Navigation Links 
  342.  
  343.       CONTINUE - SComment Tag 
  344.       BACK - Date Tag 
  345.       FORMAT TAGS 
  346.       SECTION 1 - UDMD Programming 
  347.       CONTENTS 
  348.  
  349.  
  350. ΓòÉΓòÉΓòÉ 4.2.6. SComment Tag ΓòÉΓòÉΓòÉ
  351.  
  352. .SComment Tag 
  353.  
  354.   .SComment - (Required for each keyword - one line only) (Max 120 characters) 
  355.  
  356.   The Short Comment is a one line comment regarding the migration of the 
  357. keyword. 
  358.  
  359.   Example: 
  360.  
  361.    .SComment=Parameters changed to ULONG and return structure changed
  362.  
  363. Navigation Links 
  364.  
  365.       CONTINUE - LComment Tag 
  366.       BACK - Keyword Tag 
  367.       FORMAT TAGS 
  368.       SECTION 1 - UDMD Programming 
  369.       CONTENTS 
  370.  
  371.  
  372. ΓòÉΓòÉΓòÉ 4.2.7. LComment Tag ΓòÉΓòÉΓòÉ
  373.  
  374. .LComment Tag 
  375.  
  376.   .LComment - (Required for each keyword ) (Max 120 characters each line) 
  377.  
  378.   The Long Comment is a single or multi-line comment regarding the migration of 
  379. the keyword.  Note that continued lines do not repeat the tag, but simply 
  380. require an equal ("=") sign in column 10.  The lines should be formatted 
  381. exactly as you would like to see them appear in the migrated code. 
  382.  
  383.   Example: 
  384.  
  385.    .LComment=Parameters changed to ULONG values.  Note that the variable
  386.         =to receive the number of matching entries (addressed by the
  387.         =6th parameter) has been changed to a ULONG value.
  388.         =DosFindFirst now includes additional attribute flags.  The
  389.         =previous reserved parameter (last parameter) has been
  390.         =eliminated.  The returned structure for FIL_STANDARD is now
  391.         =FILEFINDBUF3 and for FIL_QUERYEASIZE it is FILEFINDBUF4.
  392.  
  393. Navigation Links 
  394.  
  395.       CONTINUE - Sample Tag 
  396.       BACK - SComment Tag 
  397.       FORMAT TAGS 
  398.       SECTION 1 - UDMD Programming 
  399.       CONTENTS 
  400.  
  401.  
  402. ΓòÉΓòÉΓòÉ 4.2.8. Sample Tag ΓòÉΓòÉΓòÉ
  403.  
  404. .Sample Tag 
  405.  
  406.   .Sample - (Optional for each keyword ) (Max 120 characters each line) 
  407.  
  408.   The Sample is a single or multi-line set of example code regarding the 
  409. migration of the keyword.  Note that continued lines do not repeat the tag, but 
  410. simply require an equal ("=") sign in column 10.  The lines should be formatted 
  411. exactly as you would like to see them appear in the migrated code.  Typically 
  412. you will want to show an example of the code as it would appear in the source 
  413. platform code, followed by an example of its use in the target platform. 
  414.  
  415.   Example: 
  416.  
  417.    .Sample  =OS/2 1.3:
  418.         =  HDIR     hDir   = HDIR_CREATE;
  419.         =  USHORT    usCount = 1;
  420.         =  FILEFINDBUF2 FindBuf;
  421.         =  if (!DosFindFirst2 ("C:\\*.*", &hDir, FILE_NORMAL,
  422.         =     &FindBuf, sizeof(FindBuf), &usCount,
  423.         =     FIL_QUERYEASIZE, 0))
  424.         =  ...
  425.         =OS/2 2.1:
  426.         =  HDIR     hDir   = HDIR_CREATE;
  427.         =  ULONG     ulCount = 1;
  428.         =  FILEFINDBUF4 FindBuf;
  429.         =  if (!DosFindFirst ("C:\\*.*", &hDir, FILE_NORMAL,
  430.         =     &FindBuf, sizeof(FindBuf), &ulCount,
  431.         =     FIL_QUERYEASIZE))
  432.         =  ...
  433.  
  434. Navigation Links 
  435.  
  436.       CONTINUE - Prototype Tag 
  437.       BACK - LComment Tag 
  438.       FORMAT TAGS 
  439.       SECTION 1 - UDMD Programming 
  440.       CONTENTS 
  441.  
  442.  
  443. ΓòÉΓòÉΓòÉ 4.2.9. Prototype Tag ΓòÉΓòÉΓòÉ
  444.  
  445. .Prototype Tag 
  446.  
  447.   .Prototyp - (Optional for each keyword ) (Max 120 characters each line) 
  448.  
  449.   The Prototype is a single or multi-line set of code specifying the formal 
  450. function prototype for the migrated keyword.  Note that continued lines do not 
  451. repeat the tag, but simply require an equal ("=") sign in column 10.  The lines 
  452. should be formatted exactly as you would like to see them appear in the 
  453. migrated code. 
  454.  
  455.   Example: 
  456.  
  457.    .Prototyp=APIRET APIENTRY DosFindFirst(PSZ pszFileSpec, PHDIR phdir,
  458.         =  ULONG flAttribute, PVOID pfindbuf, ULONG cbBuf,
  459.         =  PULONG pcFileNames, ULONG ulInfoLevel);
  460.  
  461. Navigation Links 
  462.  
  463.       CONTINUE - Template Tag 
  464.       BACK - Sample Tag 
  465.       FORMAT TAGS 
  466.       SECTION 1 - UDMD Programming 
  467.       CONTENTS 
  468.  
  469.  
  470. ΓòÉΓòÉΓòÉ 4.2.10. Template Tag ΓòÉΓòÉΓòÉ
  471.  
  472. .Template Tag 
  473.  
  474.   .Template - (Required for Category 010) (Max 120 characters each line) 
  475.  
  476.   The Template is the code generating specification for the SMART Migration. 
  477. In the case of Category 010 Keywords, the Template is the literal replacement 
  478. string for the migrated keyword.  For Category 000, no template is required. 
  479. In the other categories, templates may be used to assist the SMART user in 
  480. formatting their own migration. 
  481.  
  482.   When SMART Migration Command Language (MiCL) is used to create a migration 
  483. command set the template may be the basis for generating the migration code. 
  484. Note that continued lines do not repeat the tag, but simply require an equal 
  485. ("=") sign in column 10. 
  486.  
  487.   Example: 
  488.  
  489.    .Template=DosFindFirst ($P1,$P2,$P3,$P4,$P5,$P6,$P7)
  490.  
  491. Navigation Links 
  492.  
  493.       CONTINUE - Reference Tag 
  494.       BACK - Prototype Tag 
  495.       FORMAT TAGS 
  496.       SECTION 1 - UDMD Programming 
  497.       CONTENTS 
  498.  
  499.  
  500. ΓòÉΓòÉΓòÉ 4.2.11. Reference Tag ΓòÉΓòÉΓòÉ
  501.  
  502. .Reference Tag 
  503.  
  504.   .Refer - (Optional) (Max 120 characters each line) 
  505.  
  506.   Reference keywords provide hypertext links to items related to the current 
  507. keyword.  The reference items are only used in the SMART Viewer to provide 
  508. quick access to additional information on related keywords.  Only one reference 
  509. item can be displayed on each .Refer tag line. 
  510.  
  511.   Any reference with a dollar character ("$") immediately preceding the 
  512. reference keyword (column 11) indicates that the reference is to an item found 
  513. elsewhere in the migration table as a keyword.  Without the dollar character, 
  514. SMART View will launch the IBM system View utility to display system help on 
  515. the keyword topic. 
  516.  
  517.   Example: 
  518.  
  519.      .Refer  =DosAllocMem
  520.      .Refer  =DosAllocSharedMem
  521.      .Refer  =$GlobalAlloc
  522.      .Refer  =$GlobalLock
  523.  
  524. Navigation Links 
  525.  
  526.       CONTINUE - Command Tag 
  527.       BACK - Template Tag 
  528.       FORMAT TAGS 
  529.       SECTION 1 - UDMD Programming 
  530.       CONTENTS 
  531.  
  532.  
  533. ΓòÉΓòÉΓòÉ 4.2.12. Command Tag ΓòÉΓòÉΓòÉ
  534.  
  535. .Command Tag 
  536.  
  537.   .Command - (Optional) (Max 120 characters each line) 
  538.  
  539.   The Command is a set of SMART Migration Commands described elsewhere in this 
  540. document.  See Section 2 - MiCL Programming Any Category of Keywords can have 
  541. command statements, but they are typically used for Category 020 and 030 
  542. Keywords in the manipulation of templates for migration code generation. 
  543.  
  544.   In the absence of Command statements the default migration will prevail. 
  545. This is: Comments only for Category 000; Literal replacement of the keyword by 
  546. the template for Category 010; and insertion of comments, templates and other 
  547. data elements in the other categories as specified by the Category Format 
  548. Options selected by the user. 
  549.  
  550.   The Command statements control the migration generated for the Keyword, 
  551. however and Short or Long Comments, Prototypes, and Sample code will 
  552. automatically be inserted in the migrated code unless omitted by a 
  553. "SmNoComment" command in this data set. Note that continued lines do not repeat 
  554. the tag, but simply require an equal ("=") sign in column 10. 
  555.  
  556.   Example: 
  557.  
  558.    .Command =/* Evaluate and output template */
  559.         =SmMigrateKeyword($T1)
  560.  
  561. Navigation Links 
  562.  
  563.       CONTINUE - Notes Tag 
  564.       BACK - Reference Tag 
  565.       FORMAT TAGS 
  566.       SECTION 1 - UDMD Programming 
  567.       CONTENTS 
  568.  
  569.  
  570. ΓòÉΓòÉΓòÉ 4.2.13. Notes Tag ΓòÉΓòÉΓòÉ
  571.  
  572. .Notes Tag 
  573.  
  574.   .Notes - (Optional) (Max 120 characters each line) 
  575.  
  576.   Notes are used to insert a set of coding lines in the Migration table for 
  577. explanation or clarification to the UDMD developer and is not used SMART 
  578. processing. 
  579.  
  580.   Notes will not be displayed in SMART Viewer. 
  581.  
  582.   You may also us a colon (":") in any coding line except for the table heading 
  583. data ( .Table, .Version, .Date, and .Notice) to indicate a comment to the 
  584. developer.  SMART will not process the comment, however the comment will 
  585. display in SMART Viewer. 
  586.  
  587.   Continued lines do not repeat the tag, but simply require an equal ("=") sign 
  588. in column 10. 
  589.  
  590.   Example: 
  591.  
  592.    .Notes  =This migration assumes that all shorts have been changed to longs.
  593.         =If not, care must be taken to properly type cast the argument variables.
  594.  
  595. Navigation Links 
  596.  
  597.       CONTINUE - UDMD Programming Notes 
  598.       BACK - Command Tags 
  599.       FORMAT TAGS 
  600.       SECTION 1 - UDMD Programming 
  601.       CONTENTS 
  602.  
  603.  
  604. ΓòÉΓòÉΓòÉ 4.2.14. UDMD Programming Notes ΓòÉΓòÉΓòÉ
  605.  
  606. .UDMD Programming Notes 
  607.  
  608.   The use of the User Defined Migration Database is effective in overriding the 
  609. SMART Migration Database for specific keywords to customize the migration and 
  610. analysis to meet the specific requirements of your code. 
  611.  
  612.   For example, you may wish to port all USHORT, SHORT and int variable types to 
  613. ULONG and LONG. You may also replace the use of NULL with simply 0.  If you are 
  614. using Common Functions, you may also wish to change all occurrences of those 
  615. function calls that are replaced by the Common Functions that you have created. 
  616.  
  617.   All of these custom changes can be performed by a few simple lines of code in 
  618. a User Defined Migration Database. 
  619.  
  620.   Since the System provided SMART Migration Databases were constructed to 
  621. handle the general cases, you may increase the effective automatic migration of 
  622. your source code and greatly reduce your migration effort by the creative use 
  623. of your own UDMD. 
  624.  
  625. Navigation Links 
  626.  
  627.       CONTINUE - Section 2 - MiCL Programming 
  628.       BACK - Notes Tag 
  629.       SECTION 1 - UDMD Programming 
  630.       CONTENTS 
  631.  
  632.  
  633. ΓòÉΓòÉΓòÉ 5. Section 2 - MiCL Programming ΓòÉΓòÉΓòÉ
  634.  
  635. Migration Command Language Programming 
  636.  
  637.         Introduction 
  638.         General Language Description 
  639.         Variables and Constants 
  640.         Strings and Quotations 
  641.         SMART Built-in Functions 
  642.         MiCL Instructions 
  643.         Event Command Procedures 
  644.         Programming Notes and Tips 
  645.  
  646.  Navigation Links 
  647.  
  648.       CONTINUE - MiCL Introduction 
  649.       BACK - UDMD Programming Notes 
  650.       SECTION 1 - UDMD Programming 
  651.       CONTENTS 
  652.  
  653.  
  654. ΓòÉΓòÉΓòÉ 5.1. MiCL Introduction ΓòÉΓòÉΓòÉ
  655.  
  656. MiCL Programming Introduction 
  657.  
  658.   SMART Version 1.0 was limited to migration changes that are straight forward 
  659. and require only literal string changes.  All of the remaining changes that are 
  660. required to be made are flagged in the source code with migration comments and 
  661. left to the developer to complete.  This provides a great deal of help in the 
  662. migration effort but is limited in this rather closed solution. 
  663.  
  664.   The SMART Migration Command Processor Language defined in this document, when 
  665. implemented within SMART, will create a flexible, open and VERY powerful 
  666. migration environment. 
  667.  
  668.   Essentially the SMART migration process can be programmed with this language. 
  669. The migration of each keyword can be programmed with context sensitive logical 
  670. statements; generating migration source code specific to the requirements of 
  671. each individual keyword encounter. 
  672.  
  673.   Furthermore, SMART takes on expert characteristics.  With appropriate 
  674. programming of the keyword commands, recurring data can be stored and reused 
  675. upon subsequent encounters of the same migration instance.  The command set has 
  676. the capability of prompting the user for required parameters and storing the 
  677. parameter for continuing use in the migration of individual keywords.  The data 
  678. obtained during a migration run can be saved in simple ASCII text format and 
  679. modified for reuse in following runs. 
  680.  
  681.   In addition to command sets processed for assigned keywords, command sets can 
  682. be programmed to execute at specific migration events, such as: pre and post 
  683. migration run, pre and post file, at the encounter of a function definition, 
  684. and so on. 
  685.  
  686.   The interactive features of this command language allow the migration 
  687. developer to customize the migration process, pausing at times during the 
  688. process, displaying specific lines of source code and allowing the user to 
  689. respond to questions from the migration command processor. 
  690.  
  691.   The SMART user can create their own migration database, or override the SMART 
  692. migration database for any desired keyword.  The user can add and modify 
  693. migration commands, customizing the migration process to take advantage of 
  694. their specific migration requirements. 
  695.  
  696.   This migration language is intentionally designed to conform closely to the 
  697. Rexx Macro Language syntax.  However, the implementation contains only a very 
  698. small subset of the Rexx capabilities and has NO interface to the Rexx Command 
  699. Processor. 
  700.  
  701.   You may also take care to note the differences between the Rexx programming 
  702. language syntax and that of SMART MiCL. 
  703.  
  704.   This document describes the capabilities and syntax of the SMART Migration 
  705. Command Language. 
  706.  
  707.   The following topics are covered: 
  708.  
  709.          General Language Description 
  710.          Variables and Constants 
  711.          Strings and quotations 
  712.          SMART Built-In Functions 
  713.          Instructions 
  714.          Other Language & Command Processor Characteristics 
  715.          - Pre and Post Command Procedures 
  716.          Programming Notes, Tips & Sample Code 
  717.  
  718.  Navigation Links 
  719.  
  720.       CONTINUE - General Language Description 
  721.       BACK - Section 2 - MiCL Programming 
  722.       CONTENTS 
  723.  
  724.  
  725. ΓòÉΓòÉΓòÉ 5.2. General Language Description ΓòÉΓòÉΓòÉ
  726.  
  727. General Language Description 
  728.  
  729.     The SMART Migration Command Language is Rexx-like in syntax. 
  730.  
  731.     All data is stored as character strings, eliminating the requirement for 
  732. data declarations. 
  733.  
  734.     Each command set is processed after a SMART Migration event - typically 
  735. after the detection of a keyword in the source code stream.  As such, 
  736. predefined variables contain many of the parameters, arguments, and conditions 
  737. encountered in the detection of the migration keyword. 
  738.  
  739.     The instructions are limited to the following set: 
  740.  
  741.         1.  Assignment 
  742.  
  743.        MyVariable = "HWND" 
  744.  
  745.         2.  Execution of a SMART built-in functions 
  746.  
  747.        rtn = SmPrompt ( "Enter variable for HAB:", "hab", BUTTON, ENTRY, OK | 
  748.       CANCEL ) 
  749.  
  750.         3.  Comparison instructions 
  751.  
  752.        IF $LCNT > "2" THEN EXIT 
  753.  
  754.        Included in this instruction set are IF, THEN, ELSE, DO-END, along with 
  755.       comparison operator =, <, >, and NOT. 
  756.  
  757.                Any number of comments can be embedded in the SMART command set 
  758.            and must be contained within the delimiters /* and */. 
  759.  
  760.                MiCL Language statements cannot be continued on multiple lines 
  761.            except for built-in function arguments (bounded by parentheses) and 
  762.            the code between the "IF-THEN" comparison instruction.  Built-in 
  763.            Function arguments cannot, however, span multiple lines if the 
  764.            function is the object of an IF-THEN comparison. 
  765.  
  766.            Navigation Links 
  767.  
  768.       CONTINUE - Variables and Constants 
  769.       BACK - MiCL Introduction 
  770.       SECTION 2 - MiCL Programming 
  771.       CONTENTS 
  772.  
  773.  
  774. ΓòÉΓòÉΓòÉ 5.3. Variables and Constants ΓòÉΓòÉΓòÉ
  775.  
  776. Variables and Constants 
  777.  
  778.  Predefined Variables 
  779.  
  780.  The SMART Migration Language Command Processor predefines a number of 
  781. variables available to the user for each keyword command set.  All predefined 
  782. variables start with a dollar sign ($). 
  783.  
  784.  The following list describes these variables: 
  785.  
  786.       $KEY           Contains the keyword string. 
  787.       $KCAT          Contains the three character key for the keyword Category, 
  788.                      i.e. 020. 
  789.       $KTYPE         Contains the three character key for the keyword Type. 
  790.       $KAREA         Contains the three character key for the keyword 
  791.                      Functional Area. 
  792.       $KIND          Contains the condition of the keyword's autonomy - TRUE 
  793.                      (1) is a stand-alone keyword statement, 0 or FALSE is an 
  794.                      embedded keyword. 
  795.       $KRTN          If the current keyword is preceeded by an equal sign, the 
  796.                      variable preceding the equal sign is stored with this 
  797.                      identifier. 
  798.       $P1 - $P99      Contains the argument string of an API keyword. 
  799.       $PCNT          Contains a value for the number of arguments for an API 
  800.                      Keyword. 
  801.       $TCNT          Contains a value for the number of Templates provided for 
  802.                      this keyword. 
  803.       $T1 - $T99      Contains the template strings for a specific keyword. 
  804.       $LFILE         Contains the fully qualified filename of the current 
  805.                      keyword encounter. 
  806.       $LLINE         Contains the line number of the current keyword encounter. 
  807.       $LCOL          Contains the current column starting position of the 
  808.                      current keyword encounter. 
  809.       .$LCNT         Contains the number of source code lines in the current 
  810.                      parsed code block. 
  811.       $Gxxxxxxxx     Contains global data assigned by the user and available by 
  812.                      any keyword in any occurrence.  The "xxxxxxxx" is a user 
  813.                      defined 8 character identifier. 
  814.       $Sxxxxxxxx     Contains keyword, static, local data assigned by the user 
  815.                      and available for every occurrence of the same keyword 
  816.                      occurrence in the current processing run. The "xxxxxxxx" 
  817.                      is a user defined 8 character identifier. 
  818.  
  819.  User defined variables 
  820.  
  821.    When you choose a name for a variable, the first character must be one of: 
  822.  
  823.     A B C...Z ! ? _ or $ (if the variable is Static or Global) 
  824.  
  825.    Lowercase letters are also allowed as a first letter and are converted to 
  826.  uppercase.  The rest of the characters can be any of the preceding characters 
  827.  ( except for $) and also 0 through 9. 
  828.  
  829.    All text not in quotations is converted to uppercase prior to processing. 
  830.  
  831.    All variables  are initialized as null character strings.  (This deviates 
  832.  from the REXX standard). 
  833.  
  834.    Single character variables can not be used. 
  835.  
  836.    Do not define variables beginning with $K, $L, $P, $T - as these variables 
  837.  are designated for system use only. 
  838.  
  839.    User defined, keyword local variables beginning with "?" can be evaluated in 
  840.  template evaluation.  Variables beginning with $G and $S are designated for 
  841.  use as Process Global and Keyword Static variables. 
  842.  
  843.  Constants 
  844.  
  845.    Numeric constants cannot be used in this version of MiCL.  Where needed use 
  846.  the literal equivalent of the number string. 
  847.  
  848.    As an example: 
  849.  
  850.        IF $LCNT > "1" THEN EXIT
  851.  
  852.  Related Topics 
  853.  
  854.       Preset Variables 
  855.       Global, Static and Local Variables 
  856.       String and Variable Evaluation 
  857.  
  858.  Navigation Links 
  859.  
  860.       CONTINUE - Strings and Quotations 
  861.       BACK - Language Description 
  862.       SECTION 2 - MiCL Programming 
  863.       CONTENTS 
  864.  
  865.  
  866. ΓòÉΓòÉΓòÉ 5.4. Strings and Quotations ΓòÉΓòÉΓòÉ
  867.  
  868. Strings and Quotations 
  869.  
  870.   A string is any group of characters inside single or double quotation marks. 
  871. Either type of quotation marks can be used, but the beginning and the ending 
  872. mark must match.  The command processor stops processing the quotation when a 
  873. quotation mark and the characters that follow remain as they were typed, with 
  874. uppercase and lowercase letters. 
  875.  
  876.   The command processor resumes interpreting when it sees a matching quotation 
  877. mark.  For example: 
  878.  
  879.    'CreateWindow'
  880.    "CreateWindow"
  881.  
  882.    are both strings in quotation. 
  883.  
  884.   To use an apostrophe (single quotation mark) or double quotation marks within 
  885. a string, use the other quotation mark around the whole string.  For example: 
  886.  
  887.    'The keyword is "CreateWindow"'
  888.  
  889.       or 
  890.  
  891.    "The keyword is 'CreateWindow'"
  892.  
  893.   You also can use a pair of quotation marks (the same as those used to mark 
  894. the string).  However, the double quotation marks may not be the first marks of 
  895. a quotation.  If an open quotation mark is immediately followed by another 
  896. quotation mark of the same type it will be interpreted as a null string in 
  897. quotation.  An example of properly used nest quotation follows: 
  898.  
  899.    "Error Condition.  ""Can't find template."""
  900.  
  901.   This is interpreted by the command processor as: 
  902.  
  903.    Error Condition.  "Can't find template."
  904.  
  905.   A nested quotation can be expressed as follows: 
  906.  
  907.    "'This string is in quotation.'"
  908.  
  909.   The preceding example is evaluated as follows:
  910.  
  911.   'This string is in quotation.'
  912.  
  913.   A literal string can be formatted by using a series of literal constants 
  914. and/or variables in an assignment instruction: 
  915.  
  916.    ASTRING = "The first parameter is: " $P1
  917.  
  918.   In this example, if the first parameter was "hWindow" the value of MYSTRING 
  919. will be: 
  920.  
  921.    The first parameter is: hWindow
  922.  
  923.   Each segment of the assignment is concatenated to the next.  Be careful to 
  924. insert spaces in quotation where spacing may be required. 
  925.  
  926.   Note that the variable $P1 was placed outside the quotation marks.  If the 
  927. variable had been placed within the quotation marks the variable would have 
  928. been assumed to be part of the literal string and not evaluated for the 
  929. expression.  Variables are not evaluated when they are placed in quotation. 
  930.  
  931.   The template is a special string.  It should not be specified with bounding 
  932. quotation marks when entered into the migration dictionary with the ".Templete" 
  933. tag.  When evaluated by the SmMigrateKeyword, SmSendToEditor, or SmOutputLine 
  934. function, the only variables that are replaced by the value of the variables 
  935. are SMART predefined variables, global and keyword static variables or user 
  936. defined local variables beginning with "?" (question mark). 
  937.  
  938.   Variables placed within quotation marks are not evaluated.  During this 
  939. evaluation, all spacing is maintained in the evaluated expression (blanks are 
  940. retained).  This differs from expression evaluation with the assignment 
  941. operator (=). 
  942.  
  943.   In expression evaluation for assignment, all variables not in quotation, are 
  944. replaced by their stored values and all items evaluated are concatenated in the 
  945. output string.  Spaces not in quotation or part of an evaluated variable are 
  946. ignored. 
  947.  
  948. Related Topics 
  949.  
  950.       Use of Templates 
  951.       String and Variable Evaluation 
  952.  
  953.  Navigation Links 
  954.  
  955.       CONTINUE - Built-In Functions 
  956.       BACK - Variables and Constants 
  957.       SECTION 2 - MiCL Programming 
  958.       CONTENTS 
  959.  
  960.  
  961. ΓòÉΓòÉΓòÉ 5.5. SMART Built-in Functions ΓòÉΓòÉΓòÉ
  962.  
  963. SMART Built-in Functions 
  964.  
  965.   There are a number of SMART functions that are callable from within the SMART 
  966. Migration Command Language.  The functions are "C" Language-like in syntax with 
  967. the function name followed by the function argument, enclosed in parenthesis 
  968. and separated by commas. 
  969.  
  970.   The success value of the function call will be the returned and can be 
  971. assigned to a user defined variable when the function is called. These 
  972. functions include the following: 
  973.  
  974.          SmDisplayDlg( ) 
  975.          SmGetListName( ) 
  976.          SmGetListPath( ) 
  977.          SmGetSmartPath( ) 
  978.          SmIgnoreKeyword( ) 
  979.          SmListDlg( ) 
  980.          SmLoadVars( ) 
  981.          SmMigrateKeyword( ) 
  982.          SmNoComment( ) 
  983.          SmNoMigrate( ) 
  984.          SmOutputLine( ) 
  985.          SmOutputNote( ) 
  986.          SmPromptDlg( ) 
  987.          SmRemove( ) 
  988.          SmSaveVars( ) 
  989.          SmSendToEditor( ) 
  990.  
  991.  Navigation Links 
  992.  
  993.       CONTINUE - SmDisplayDlg( ) 
  994.       BACK - Strings and Quotations 
  995.       SECTION 2 - MiCL Programming 
  996.       CONTENTS 
  997.  
  998.  
  999. ΓòÉΓòÉΓòÉ 5.5.1. SmDisplayDlg( ) ΓòÉΓòÉΓòÉ
  1000.  
  1001. .SmDisplayDlg( ) 
  1002.  
  1003.   SmDisplayDlg (  Display_String, Option_Return, Control_Options ) 
  1004.  
  1005.   SmDisplayDlg creates a popup dialog to display a message string.  Processing 
  1006. will be halted and the dialog will remain displayed until the user presses one 
  1007. of the control option buttons. 
  1008.  
  1009.   Up to four programmable push-buttons can be defined in this call. 
  1010. Accelerators can be assigned to the push-buttons by using the tilde (~) 
  1011. character preceding the push-button display character of the desired 
  1012. accelerator key.  The value of the returned option selected by the user will 
  1013. not contain this tilde character. 
  1014.  
  1015.   Description for the arguments of this function follows: 
  1016.  
  1017.       Display_String           The user supplied literal string to display (up 
  1018.                                to 80 characters). This argument can also be a 
  1019.                                variable whose value contains the string to 
  1020.                                display. 
  1021.       Option_Return            A variable to contain the literal value of the 
  1022.                                button selected by the user to terminate the 
  1023.                                display (see Control_Options). 
  1024.       Control_Options          Up to four strings representing the 
  1025.                                identification of the push-buttons to appear on 
  1026.                                the display.  The buttons will appear in the 
  1027.                                order as they appear in this argument.  Each 
  1028.                                button ID must be separated by the "|" 
  1029.                                character.  Upper and lower case, along with the 
  1030.                                aforementioned tilde can be used.  By default 
  1031.                                the first button responds to the "Enter" key, 
  1032.                                and the second button responds to the "ESCape" 
  1033.                                key. 
  1034.       result                   A success value for the function. 1= Ok. 
  1035.                                0=Error. 
  1036.  
  1037.    Example: 
  1038.  
  1039.      RTN =  SmDisplayDlg("Verify Processing this Keyword",
  1040.                 OPTION, ~Ok | ~Cancel |  ~Abort )
  1041.      IF OPTION = "ABORT" THEN TERMINATE
  1042.  
  1043.    Notes: 
  1044.  
  1045.    The position of the Display Dialog on the user desktop is saved at the 
  1046.  termination of the dialog.  The user can move the dialog panel to a convenient 
  1047.  position.  Subsequent dialog displays from this function call will appear in 
  1048.  the same position. 
  1049.  
  1050.    This dialog can be used to suspend processing while displaying the source 
  1051.  code at the current keyword encounter from the use of the SmSendToEditor 
  1052.  command function. 
  1053.  
  1054.  Related Topics 
  1055.  
  1056.       Use of Dialog Functions 
  1057.       Launching the Editor 
  1058.  
  1059.  Navigation Links 
  1060.  
  1061.       CONTINUE - SmGetListName 
  1062.       BACK - Built-In Functions 
  1063.       SECTION 2 - MiCL Programming 
  1064.       CONTENTS 
  1065.  
  1066.  
  1067. ΓòÉΓòÉΓòÉ 5.5.2. SmGetListName( ) ΓòÉΓòÉΓòÉ
  1068.  
  1069. .SmGetListName( ) 
  1070.  
  1071.   SmGetListName ( Return_Variable ) 
  1072.  
  1073.   SmGetListName returns the fully qualified filename of the current 
  1074. List-of-Files used in the migration process. 
  1075.  
  1076.   Description for the arguments of this function follows: 
  1077.  
  1078.       Return_Variable          A variable to contain the filename of the 
  1079.                                List-of-Files. 
  1080.       result                   A success value for the function. 1= Ok. 
  1081.                                0=Error. 
  1082.  
  1083.    Example: 
  1084.  
  1085.      SmGetListName( LISTNAME )
  1086.      IF LISTNAME = "C:\MYAPP\LIST.LST"
  1087.        THEN
  1088.         SmLoadVars( "C:\MYAPP\VARS1.DAT" )
  1089.        ELSE
  1090.         SmLoadVars( "C:\MYAPP\VARS2.DAT" )
  1091.  
  1092.  Navigation Links 
  1093.  
  1094.       CONTINUE - SmGetListPath 
  1095.       BACK - SmDisplayDlg 
  1096.       BUILT-IN FUNCTIONS 
  1097.       SECTION 2 - MiCL Programming 
  1098.       CONTENTS 
  1099.  
  1100.  
  1101. ΓòÉΓòÉΓòÉ 5.5.3. SmGetListPath( ) ΓòÉΓòÉΓòÉ
  1102.  
  1103. .SmGetListPath( ) 
  1104.  
  1105.   SmGetListPath ( Return_Variable ) 
  1106.  
  1107.   SmGetListPath returns the directory path of the current List-of-Files used in 
  1108. the migration process. 
  1109.  
  1110.   Description for the arguments of this function follows: 
  1111.  
  1112.       Return_Variable          A variable to contain the path of the 
  1113.                                List-of-Files. 
  1114.       result                   A success value for the function. 1= Ok. 
  1115.                                0=Error. 
  1116.  
  1117.    Example: 
  1118.  
  1119.        SmGetListPath( LISTPATH )
  1120.        VARNAME = LISTPATH "\VARS.DAT"
  1121.        SmLoadVars( VARNAME )
  1122.  
  1123.  Navigation Links 
  1124.  
  1125.       CONTINUE - SmGetSmartPath 
  1126.       BACK - SmGetListName 
  1127.       BUILT-IN FUNCTIONS 
  1128.       SECTION 2 - MiCL Programming 
  1129.       CONTENTS 
  1130.  
  1131.  
  1132. ΓòÉΓòÉΓòÉ 5.5.4. SmGetSmartPath( ) ΓòÉΓòÉΓòÉ
  1133.  
  1134. .SmGetSmartPath( ) 
  1135.  
  1136.   SmGetSmartPath ( Return_Variable ) 
  1137.  
  1138.   SmGetSmartPath returns the directory path of the SMART application 
  1139. executable. 
  1140.  
  1141.   Description for the arguments of this function follows: 
  1142.  
  1143.       Return_Variable          A variable to contain the path of the SMART 
  1144.                                executable. 
  1145.       result                   A success value for the function. 1= Ok. 
  1146.                                0=Error. 
  1147.  
  1148.    Example: 
  1149.  
  1150.        SmGetSmartPath( SMARTPATH )
  1151.        VARNAME = SMARTPATH "\DATA\VARS.DAT"
  1152.        SmLoadVars( VARNAME )
  1153.  
  1154.  Navigation Links 
  1155.  
  1156.       CONTINUE - SmIgnoreKeyword 
  1157.       BACK - SmGetListPath 
  1158.       BUILT-IN FUNCTIONS 
  1159.       SECTION 2 - MiCL Programming 
  1160.       CONTENTS 
  1161.  
  1162.  
  1163. ΓòÉΓòÉΓòÉ 5.5.5. SmIgnoreKeyword( ) ΓòÉΓòÉΓòÉ
  1164.  
  1165. .SmIgnoreKeyword( ) 
  1166.  
  1167.   SmIgnoreKeyword ( ) 
  1168.  
  1169.   SmIgnoreKeyword excludes processing of the current keyword.  This is 
  1170. equivalent to entering the keyword in an exclude list for processing.  However, 
  1171. since this command appears in the MiCL Language, it can be dynamically and 
  1172. interactively applied. 
  1173.  
  1174.   No comments for this keyword will appear in the migrated output file. 
  1175.  
  1176.   See also: SmNoMigrate and DEFAULT. 
  1177.  
  1178.   Description for the arguments of this function follows: 
  1179.  
  1180.       result                   A success value for the function. 1= Ok. 
  1181.                                0=Error. 
  1182.  
  1183.    Example: 
  1184.  
  1185.      IF $SIgnore = "" THEN
  1186.        DO
  1187.         STRING = "Verify Ignore Keyword on all: " $KEY
  1188.         SmDisplay( STRING, $SIgnore, ~Yes | ~NO | ~Abort)
  1189.        END
  1190.  
  1191.      IF $SIgnore = "Abort" THEN TERMINATE
  1192.      IF $SIgnore = "Yes" THEN
  1193.        SmIgnoreKeyword( )
  1194.      ...
  1195.  
  1196.    Notes: 
  1197.  
  1198.    Note in the example a static variable was defined to contain the user 
  1199.  response to the question of ignoring the current keyword.  Upon subsequent 
  1200.  encounters this variable will contain "Yes" or "No" and the display is not 
  1201.  required. 
  1202.  
  1203.    If this static variable is saved at the end of the process and reloaded at 
  1204.  the beginning of other process runs, then this variable will always respond to 
  1205.  the initial user query. 
  1206.  
  1207.    By using SmSendToEditor followed by SmDisplayDlg you can allow the user to 
  1208.  view each encounter of the keyword and enter the appropriate response for 
  1209.  ignoring the keyword or not ignoring the keyword for migration. 
  1210.  
  1211.  Related Topics 
  1212.  
  1213.       Migration Control 
  1214.       SmNoMigrate 
  1215.  
  1216.  Navigation Links 
  1217.  
  1218.       CONTINUE - SmListDlg 
  1219.       BACK - SmGetSmartPath 
  1220.       BUILT-IN FUNCTIONS 
  1221.       SECTION 2 - MiCL Programming 
  1222.       CONTENTS 
  1223.  
  1224.  
  1225. ΓòÉΓòÉΓòÉ 5.5.6. SmListDlg( ) ΓòÉΓòÉΓòÉ
  1226.  
  1227. .SmListDlg( ) 
  1228.  
  1229.   SmListDlg (  Display_String, Edit_String, Option_Return, 
  1230. String_Return_Variable, Filename) 
  1231.  
  1232.   SmListDlg creates a popup dialog to provide a list of options to select or 
  1233. maintain.  This is ideal for interactive processing where a user can select 
  1234. from a list of templates or processing options.  The user will also have the 
  1235. opportunity to add new items to the list. 
  1236.  
  1237.   The list of items is stored and retrieved as a text file with the designated 
  1238. filename in the argument of this function call. 
  1239.  
  1240.   The response buttons on this dialog are fixed, but both the button name and 
  1241. the selected string will be returned to the variables as specified by the 
  1242. arguments of this call. 
  1243.  
  1244.   Processing will be halted and the dialog will remain displayed until the user 
  1245. presses one of the control option buttons. 
  1246.  
  1247.   Description for the arguments of this function follows: 
  1248.  
  1249.       Display_String           The literal string to display (up to 80 
  1250.                                characters) above the list box. This argument 
  1251.                                can also be a variable that contains the string 
  1252.                                to display. 
  1253.       Edit_String              The default edit string that will be displayed 
  1254.                                and highlighted above the list box. 
  1255.       Option_Return             A variable to contain the literal value of the 
  1256.                                button selected by the user to terminate the 
  1257.                                display.  "Process", "Cancel", "Store" or 
  1258.                                "Terminate" is valid. 
  1259.       String_Return_Variable   A Variable to contain the list box selection if 
  1260.                                the user terminates with "Process". 
  1261.       Filename                 The filename to contain the text items to 
  1262.                                display in the listbox. If the user terminates 
  1263.                                the dialog with "Process" or "Store", the items 
  1264.                                contained in the current list box, including any 
  1265.                                changes will be stored in the designated 
  1266.                                filename. 
  1267.       result                   A success value for the function. 1= Ok. 
  1268.                                0=Error. 
  1269.  
  1270.    Example: 
  1271.  
  1272.      SmSendToEditor( "$LFile($LLine:$LCol)R" )
  1273.      SmListDlg("Select the choice for HANDLE replacement",
  1274.            $Shandle, OPTION, $Shandle, "HANDLE.DAT" )
  1275.      IF OPTION = "Terminate" THEN TERMINATE
  1276.      IF OPTION = "Cancel" THEN EXIT
  1277.      IF OPTION = "Store" THEN EXIT
  1278.      SmMigrateKeyword( $Shandle )
  1279.  
  1280.    Notes: 
  1281.  
  1282.    The position of the List Dialog on the user desktop is saved at the 
  1283.  termination of the dialog.  The user can move the dialog panel to a convenient 
  1284.  position.  Subsequent displays of this dialog will appear in the same 
  1285.  position. 
  1286.  
  1287.    This dialog can be used to suspend processing while displaying the source 
  1288.  code at the current keyword encounter from the use of the SmSendToEditor 
  1289.  command function. 
  1290.  
  1291.    If the filename containing the list to display does not exist, the user will 
  1292.  be advised and can proceed by creating a new file with their own entries, or 
  1293.  canceling this step. 
  1294.  
  1295.    The advantage of this dialog is that the user can easily select an existing 
  1296.  item in the list, or modify the list.  The list will be saved (upon 
  1297.  appropriate termination of the dialog) and the stored items will appear in 
  1298.  subsequent encounters of the keyword. 
  1299.  
  1300.    Note the use of the static variable $Shandle in the example above.  By using 
  1301.  this variable as both the Edit_String and the String_Return_Variable 
  1302.  arguments, the selected string returned by the user will appear as the default 
  1303.  option in the next encounter. 
  1304.  
  1305.    Also note the use of SmSendToEditor. 
  1306.  
  1307.   In this example the source code at the point of encounter was displayed to 
  1308.  allow the user to see the keyword in context before making a listbox 
  1309.  selection. 
  1310.  
  1311.    The filename specified in this function call does not require a fully 
  1312.  qualified path if the file is located in the same directory as the 
  1313.  List-of-Files file for the migration process.  The path for the List-of-Files 
  1314.  or the main SMART directory path can be obtained by appropriate built-in 
  1315.  function calls. 
  1316.  
  1317.  Related Topics 
  1318.  
  1319.       Use of Dialog Functions 
  1320.       Launching the Editor 
  1321.  
  1322.  Navigation Links 
  1323.  
  1324.       CONTINUE - SmLoadVars 
  1325.       BACK - SmIngoreKeyword 
  1326.       BUILT-IN FUNCTIONS 
  1327.       SECTION 2 - MiCL Programming 
  1328.       CONTENTS 
  1329.  
  1330.  
  1331. ΓòÉΓòÉΓòÉ 5.5.7. SmLoadVars( ) ΓòÉΓòÉΓòÉ
  1332.  
  1333. .SmLoadVars( ) 
  1334.  
  1335.   SmLoadVars ( Filename ) 
  1336.  
  1337.   SmLoadVariables reads the ASCII text file specified by filename to assign 
  1338. values to global and keyword static variables.  The file can be created using a 
  1339. text editor or can be the stored result of the SmSaveVars function call. 
  1340.  
  1341.   Description for the arguments of this function follows: 
  1342.  
  1343.       Filename                 The filename of the output file.  If the 
  1344.                                filename is not fully qualified, the default 
  1345.                                directory is the directory containing the 
  1346.                                currently selected List-Of-files. 
  1347.       result                   A success value for the function. 1= Ok. 
  1348.                                0=Error. 
  1349.  
  1350.    Example: 
  1351.  
  1352.      SmLoadVars ( "VARS1.DAT" )
  1353.  
  1354.    Notes: 
  1355.  
  1356.    Each line of the file containing the stored variables and their values must 
  1357.  contain an assignment statement of the form: 
  1358.  
  1359.      $Gvariable = value  (for Process Global variables)
  1360.  
  1361.       or 
  1362.  
  1363.      Keyword.$Svariable=value  (for Keyword Static variables)
  1364.  
  1365.    For example: 
  1366.  
  1367.      $Ghab=hab
  1368.      WinCreateMessage.$Shandle=hwnd
  1369.  
  1370.    Note in the case of keyword static variables, the variable is keyword 
  1371.  identified by preceding the variable name with the keyword followed by a 
  1372.  period (.).  The keyword in this case is case sensitive an should appear 
  1373.  exactly as it is coded in the migration database. 
  1374.  
  1375.    This call is best utilized by including this function in a preprocess 
  1376.  command set ($$PRE_PROCESS) with the companion call, SmSaveVars, performed as 
  1377.  a part of the $$POST_PROCESS command set.  This effectively restores and saves 
  1378.  all global and keyword static variable values. 
  1379.  
  1380.  Related Topics 
  1381.  
  1382.       Pre and Post Command Sets 
  1383.  
  1384.  Navigation Links 
  1385.  
  1386.       CONTINUE - SmMigrateKeyword 
  1387.       BACK - SmListDlg 
  1388.       BUILT-IN FUNCTIONS 
  1389.       SECTION 2 - MiCL Programming 
  1390.       CONTENTS 
  1391.  
  1392.  
  1393. ΓòÉΓòÉΓòÉ 5.5.8. SmMigrateKeyword( ) ΓòÉΓòÉΓòÉ
  1394.  
  1395. .SmMigrateKeyword( ) 
  1396.  
  1397.   SmMigrateKeyword ( Template ) 
  1398.  
  1399.   The SmMigrateKeyword command replaces the current keyword with the argument 
  1400. of this command.  If the keyword is an API keyword, then this output will 
  1401. replace both the keyword and all arguments of the API call including the 
  1402. opening and closing parentheses. Typically this argument will be a template for 
  1403. the keyword.  However it can be a literal string formatted in this command set. 
  1404. The argument can consist of a single variable or literal string. 
  1405.  
  1406.   This command MUST appear in each command set unless the keyword is to remain, 
  1407. blank, or the SmRemove command is used to remove source code related to the 
  1408. keyword. Failure to do so will result in a NULL output in the migrated source 
  1409. code. 
  1410.  
  1411.   Description for the arguments of this function follows: 
  1412.  
  1413.       Template                 A variable containing a keyword template, or a 
  1414.                                variable containing a string to be processed as 
  1415.                                a template, or a literal to be used as a 
  1416.                                template. 
  1417.       result                   A success value for the function. 1= Ok. 
  1418.                                0=Error. 
  1419.  
  1420.    Example: 
  1421.  
  1422.      NEWTEMPLATE = "WinQueryWindow( $P1, QW_PARENT)"
  1423.      SmMigrateKeyword( NEWTEMPLATE )
  1424.  
  1425.    Notes: 
  1426.  
  1427.    Note that the argument of the SmMigrateKeyword is evaluated as a template. 
  1428.  Only $variables and ?variables are replaced with their values and all spacing 
  1429.  will remain intact. 
  1430.  
  1431.    Only ONE call to SmMigrateKeyword should be made while processing a keyword 
  1432.  encounter.  If multiple calls are made, only the last call will create the 
  1433.  migration code. 
  1434.  
  1435.    DO NOT include a semicolon at the end of an API template to be used in this 
  1436.  function.  The keyword may be an embedded argument of a higher API call and 
  1437.  not require a semicolon.  Note that in the case of an API keyword, both the 
  1438.  keyword string and ALL arguments including the bounding parentheses are 
  1439.  replaced by the argument of this function call. 
  1440.  
  1441.    If multiple lines are to be output in the migration you must use this 
  1442.  function call, or SmRemove, along with the SmOutputLine function. 
  1443.  
  1444.  Related Topics 
  1445.  
  1446.       Preset Variables 
  1447.       Use of Templates 
  1448.       Migration Control 
  1449.       Migration Notes and Comments 
  1450.       String and Variable Evaluation 
  1451.  
  1452.  Navigation Links 
  1453.  
  1454.       CONTINUE - SmNoComment 
  1455.       BACK - SmLoadVars 
  1456.       BUILT-IN FUNCTIONS 
  1457.       SECTION 2 - MiCL Programming 
  1458.       CONTENTS 
  1459.  
  1460.  
  1461. ΓòÉΓòÉΓòÉ 5.5.9. SmNoComment( ) ΓòÉΓòÉΓòÉ
  1462.  
  1463. .SmNoComment( ) 
  1464.  
  1465.   SmNoComment (  param1 | [ param2 | ... ] ) 
  1466.  
  1467.   SmNoComment turns off the designated migration comments for this encounter of 
  1468. the current keyword only. 
  1469.  
  1470.   Description for the arguments of this function follows: 
  1471.  
  1472.       param                     The following parameters are valid for this 
  1473.                                call: LCOMMENT, SCOMMENT, SAMPLE, PROTOTYPE, 
  1474.                                TEMPLATE ALL (All comments). When specifying 
  1475.                                multiple parameters use the "|" character to 
  1476.                                separate each parameter. 
  1477.       result                   A success value for the function. 1= Ok. 
  1478.                                0=Error. 
  1479.  
  1480.    Example: 
  1481.  
  1482.      SmNoComment( LCOMMENT | SAMPLE | PROTOTYPE | TEMPLATE )
  1483.  
  1484.    Notes: 
  1485.  
  1486.    Please note the interaction and capabilities of the SmIgnoreKeyword, 
  1487.  SmNoMigrate, and SmNoComment commands. 
  1488.  
  1489.    SmIgnoreKeyword acts if the keyword did not exist in the migration table - 
  1490.  no processing is performed on this keyword. 
  1491.  
  1492.    SmNoMigrate causes no change in the migrated output code, but retains any 
  1493.  comments that you may wish to insert in the output code.  These comments can 
  1494.  be modified by using the SmNoComment command turning off any or all migration 
  1495.  comments, and by using the SmOutputNote to insert custom comments in the 
  1496.  output code. 
  1497.  
  1498.  Related Topics 
  1499.  
  1500.       Migration Notes and Comments 
  1501.  
  1502.  Navigation Links 
  1503.  
  1504.       CONTINUE - SmNoMigrate 
  1505.       BACK - SmMigrateKeyword 
  1506.       BUILT-IN FUNCTIONS 
  1507.       SECTION 2 - MiCL Programming 
  1508.       CONTENTS 
  1509.  
  1510.  
  1511. ΓòÉΓòÉΓòÉ 5.5.10. SmNoMigrate( ) ΓòÉΓòÉΓòÉ
  1512.  
  1513. .SmNoMigrate( ) 
  1514.  
  1515.   SmNoMigrate (  ) 
  1516.  
  1517.   SmNoMigrate suspends any migration processing for the current keyword 
  1518. instance.  The output will look just like the input. However, all comments 
  1519. scheduled to be inserted in the output source code will be processed.  (In the 
  1520. SmIgnoreKeyword call, the keyword processing is completely ignored). 
  1521.  
  1522.   In combination with SmNoComment(ALL) the migration for this keyword will be 
  1523. ignored.  You may use SmNoMigrate with SmNoComment and SmOutputNote to insert a 
  1524. processing note at the point of this keyword encounter. 
  1525.  
  1526.   Description for the arguments of this function follows: 
  1527.  
  1528.       arguments                None. 
  1529.       result                   A success value for the function. 1= Ok. 
  1530.                                0=Error. 
  1531.  
  1532.    Example 1: 
  1533.  
  1534.      SmNoMigrate( )
  1535.      SmNoComment( ALL )
  1536.      NOTE = "Keyword: " $KEY must be reworked for complete migration."
  1537.      SmOutputNote(  NOTE )
  1538.  
  1539.    Example 2: 
  1540.  
  1541.      OPTION = ""
  1542.      SmNoComment(ALL)
  1543.      IF $Scontrol NOT = "No Verify" THEN
  1544.        SmSendToEditor( "$LFile($LLine:$LCol)R" )
  1545.      IF $Sreplaced = "" THEN
  1546.        DO
  1547.         PROMPT = "Enter replacement string for: " $KEY
  1548.         SmPromptDlg(PROMPT, "", OPTION, $Sreplaced, ~Ok | ~Abort )
  1549.        END
  1550.      IF OPTION = "Abort" THEN TERMINATE
  1551.      IF $Sverify = "No Verify" THEN
  1552.        DO
  1553.         DISPLAY = "Verify replacement of: " $KEY " by " $Sreplaced
  1554.         SmDisplayDlg(DISPLAY, $Scontrol,
  1555.                 ~Yes | ~NO | No ~Verify | ~Abort)
  1556.        END
  1557.      IF $Scontrol = "Abort" THEN TERMINATE
  1558.      IF $Scontrol = "No" THEN
  1559.         DO
  1560.           SmNoMigrate( )
  1561.           EXIT
  1562.         END
  1563.        ELSE
  1564.         SmMigrateKeyword( $Sreplaced )
  1565.  
  1566.    Notes: 
  1567.  
  1568.    Example 2 is a search and replace with initial replacement prompt and a 
  1569.  verify for each encounter.  If "No Verify" is selected, the process will 
  1570.  automatically perform the replacement without any notification. 
  1571.  
  1572.  Related Topics 
  1573.  
  1574.       Migration Control 
  1575.  
  1576.  Navigation Links 
  1577.  
  1578.       CONTINUE - SmOutputLine 
  1579.       BACK - SmNoComment 
  1580.       BUILT-IN FUNCTIONS 
  1581.       SECTION 2 - MiCL Programming 
  1582.       CONTENTS 
  1583.  
  1584.  
  1585. ΓòÉΓòÉΓòÉ 5.5.11. SmOutputLine( ) ΓòÉΓòÉΓòÉ
  1586.  
  1587. .SmOutputLine ( ) 
  1588.  
  1589.   SmOutputLine ( Template ) 
  1590.  
  1591.   The SmOutputLine command is similar to SmMigrateKeyword , except that this 
  1592. command is used to generate additional output lines (following the migration). 
  1593. This command is useful to generate multiple lines of migration code in Category 
  1594. 030 migration encounters, or where program code or comments are to be required 
  1595. to be placed in the output. 
  1596.  
  1597.   This function is different from SmOutputNote .  The generated code will not 
  1598. be in comments and will appear in the output stream immediately following the 
  1599. code block containing the  encountered keyword.  The argument for this function 
  1600. can be a variable or a literal string. 
  1601.  
  1602.   The value of the argument will be evaluated (if not a literal string) by 
  1603. replacing all variables beginning with "$" (dollar sign) or "?" (question 
  1604. mark). Any variable referenced but not defined will be replaced by a null 
  1605. character. 
  1606.  
  1607.   Description for the arguments of this function follows: 
  1608.  
  1609.       Template                 A variable containing a keyword template, or a 
  1610.                                variable containing a string to be processed as 
  1611.                                a template, or a literal to be used as a 
  1612.                                template. 
  1613.       result                   A success value for the function. 1= Ok. 
  1614.                                0=Error. 
  1615.  
  1616.    Example 1: 
  1617.  
  1618.      SmNoMigrate( )
  1619.      SmNoComment( ALL )
  1620.      NOTE = "Keyword: " $KEY must be reworked for complete migration."
  1621.      SmOutputNote(  NOTE )
  1622.  
  1623.    Example 2: 
  1624.  
  1625.      IF $KIND = "TRUE" THEN
  1626.        DO
  1627.         SmMigrateKeyword( $T1 )
  1628.         SmOutputLine( $T2 )
  1629.        END
  1630.      ELSE
  1631.        ...
  1632.  
  1633.    Notes: 
  1634.  
  1635.    If the migrating keyword is embedded in the arguments of a higher level 
  1636.  function call a comment will be generated in the output code and the 
  1637.  additional output line will be supressed. 
  1638.  
  1639.    If the keyword is within an 'if', 'while', or 'for' statement as a single 
  1640.  API function call, braces will be added, if required, to insure that all of 
  1641.  the generated lines are properly placed within the scope of the statement. 
  1642.  
  1643.    Note that the Keyword Independent Flag "$KIND" contains a literal value of 
  1644.  "TRUE" or "FALSE". 
  1645.  
  1646.    When creating the template or literal string for each of the generated 
  1647.  additional lines of code, remember that a keyword is not being replaced by the 
  1648.  code line, but instead the line is placed in full in the output stream.  As 
  1649.  such, a semicolon at the end of the line may be necessary to terminate a 
  1650.  statement. 
  1651.  
  1652.  Related Topics 
  1653.  
  1654.       Use of Templates 
  1655.       Migration Control 
  1656.       Migration Notes and Comments 
  1657.       String and Variable Evaluation 
  1658.  
  1659.  Navigation Links 
  1660.  
  1661.       CONTINUE - SmOutputNote 
  1662.       BACK - SmNoMigrate 
  1663.       BUILT-IN FUNCTIONS 
  1664.       SECTION 2 - MiCL Programming 
  1665.       CONTENTS 
  1666.  
  1667.  
  1668. ΓòÉΓòÉΓòÉ 5.5.12. SmOutputNote( ) ΓòÉΓòÉΓòÉ
  1669.  
  1670. .SmOutputNote ( ) 
  1671.  
  1672.   SmOutputNote ( Line ) 
  1673.  
  1674.   SmOutputNote places a string in the output migration comments.  This comment 
  1675. is tagged as "SM$:I".  This argument should be limited to a maximum of 80 
  1676. characters for each note line created. 
  1677.  
  1678.   Description for the arguments of this function follows: 
  1679.  
  1680.       Line                     Variable containing an note line or a literal 
  1681.                                string. 
  1682.       result                   A success value for the function. 1= Ok. 
  1683.                                0=Error. 
  1684.  
  1685.    Example: 
  1686.  
  1687.      NOTE = "Keyword is embedded and cannot be properly migrated: " $KEY
  1688.      SmOutputNote ( NOTE )
  1689.      ...
  1690.  
  1691.    Notes: 
  1692.  
  1693.    Any notes generated in the output code will be appropriately placed in 
  1694.  comments along with the other migration comments. 
  1695.  
  1696.    Suppression of migration comments with the SmNoComment command will not 
  1697.  affect the generation of notes created with this built-in function call. 
  1698.  
  1699.    It is helpful to identify the keyword that is the object of the note to 
  1700.  insure that the user clearly understands which keyword the generated comment 
  1701.  is associated. 
  1702.  
  1703.  Related Topics 
  1704.  
  1705.       Migration Notes and Comments 
  1706.  
  1707.  Navigation Links 
  1708.  
  1709.       CONTINUE - SmPromptDlg 
  1710.       BACK - SmOutputLine 
  1711.       BUILT-IN FUNCTIONS 
  1712.       SECTION 2 - MiCL Programming 
  1713.       CONTENTS 
  1714.  
  1715.  
  1716. ΓòÉΓòÉΓòÉ 5.5.13. SmPromptDlg( ) ΓòÉΓòÉΓòÉ
  1717.  
  1718. .SmPromptDlg ( ) 
  1719.  
  1720.   SmPromptDlg ( Display_String, Edit_String, Option_Return, 
  1721. String_Return_Variable, Control_Options) 
  1722.  
  1723.   SmPromptDlg creates a popup dialog and waits for a user response.  This 
  1724. dialog is useful for obtaining variable names from the user at run time. 
  1725.  
  1726.  Up to four programmable push-buttons can be defined in this call. 
  1727. Accelerators can be assigned to the push-buttons by using the tilde (~) 
  1728. character preceding the push-button display character of the desired 
  1729. accelerator key.  The value of the returned option selected by the user will 
  1730. not contain this tilde character. 
  1731.  
  1732.   Description for the arguments of this function follows: 
  1733.  
  1734.       Display_String           The user supplied literal string to display (up 
  1735.                                to 80 characters). This argument can also be a 
  1736.                                variable that contains the string to display. 
  1737.       Edit_String              The default edit string that will be displayed 
  1738.                                and highlighted in he entry panel ready for 
  1739.                                change. 
  1740.       Option_Return            A variable to contain the literal value of the 
  1741.                                button selected by the user to terminate the 
  1742.                                display (see Control_Options). 
  1743.       String_Return_Variable   A variable to contain the value of the entry 
  1744.                                field upon termination of the dialog.  This will 
  1745.                                contain the user entry to the prompt of this 
  1746.                                dialog. 
  1747.       Control_Options          Up to four strings representing the 
  1748.                                identification of the push-buttons to appear on 
  1749.                                the display.  The buttons will appear in the 
  1750.                                order as they appear in this argument.  Each 
  1751.                                button ID must be separated by the "|" 
  1752.                                character.  Upper and lower case, along with the 
  1753.                                aforementioned tilde can be used.  By default 
  1754.                                the first button responds to the "Enter" key, 
  1755.                                and the second button responds to the "ESCape" 
  1756.                                key. 
  1757.       result                   A success value for the function. 1= Ok. 
  1758.                                0=Error. 
  1759.  
  1760.    Example: 
  1761.  
  1762.      IF $Shab = "" THEN $Shab = "hab"
  1763.      RTN =  SmPromptDlg("Please enter the variable name used for HAB",
  1764.               $Shab, OPTION, $Shab, ~Ok | ~Cancel |  ~Abort )
  1765.      IF OPTION = "ABORT" THEN TERMINATE
  1766.  
  1767.    Notes: 
  1768.  
  1769.    The position of the Prompt Dialog on the user desktop is saved at the 
  1770.  termination of the dialog.  The user can move the dialog panel to a convenient 
  1771.  position.  Subsequent displays of this dialog type will appear in the same 
  1772.  position. 
  1773.  
  1774.    The use of a single keyword static variable for both the Edit_String and the 
  1775.  String_Return_Variable give the user his previous entry as the initial 
  1776.  default. 
  1777.  
  1778.  Related Topics 
  1779.  
  1780.       Use of Dialog Functions 
  1781.       Launching the Editor 
  1782.  
  1783.  Navigation Links 
  1784.  
  1785.       CONTINUE - SmRemove 
  1786.       BACK - SmOutputNote 
  1787.       BUILT-IN FUNCTIONS 
  1788.       SECTION 2 - MiCL Programming 
  1789.       CONTENTS 
  1790.  
  1791.  
  1792. ΓòÉΓòÉΓòÉ 5.5.14. SmRemove( ) ΓòÉΓòÉΓòÉ
  1793.  
  1794. .SmRemove ( ) 
  1795.  
  1796.   SmRemove ( Option ) 
  1797.  
  1798.   SmRemove will remove either the keyword, the source code line in which the 
  1799. keyword is found or the complete statement block at has been parsed as part of 
  1800. the keyword statement. 
  1801.  
  1802.   The value of the options argument specifies 'KEYWORD', 'LINE', or 'BLOCK'. 
  1803.  
  1804.   Due to the complexity of the coding syntax that may occur in the source code, 
  1805. it is advised that the user have the opportunity to view the context of the 
  1806. keyword to determine if the removal is appropriate. 
  1807.  
  1808.   Description for the arguments of this function follows: 
  1809.  
  1810.       Option                   'KEYWORD', 'LINE', or 'BLOCK'. 
  1811.       result                   A success value for the function. 1= Ok. 
  1812.                                0=Error. 
  1813.  
  1814.    Example: 
  1815.  
  1816.      SmSendToEditor( "$LFile($LLine:$LCol)R" )
  1817.      DISPLAY = "Choose Removal Option for: " $KEY
  1818.      SmDisplayDlg( DISPLAY, OPTION,
  1819.             ~Line | ~Cancel | ~Keyword | ~Block)
  1820.      IF OPTION = "Cancel" THEN
  1821.        DO
  1822.         SmNoMigrate()
  1823.         EXIT
  1824.        END
  1825.      ELSE
  1826.        SmRemove( OPTION )
  1827.  
  1828.    Notes: 
  1829.  
  1830.    You can use SmRemove along with SmOutputLine to replace source code with 
  1831.  newly generated output code. 
  1832.  
  1833.    Using SmRemove with the "KEYWORD" option replaces the keyword. (and any 
  1834.  arguments, if the keyword is a API function) with a null string. 
  1835.  
  1836.    Note however that the code surrounding the keyword remains intact (including 
  1837.  a terminating semicolon if it appears).  A stand alone API function call 
  1838.  should by removed with the "LINE" option to insure that the termination 
  1839.  semicolon is properly erased in the output. 
  1840.  
  1841.  Related Topics 
  1842.  
  1843.       Migration Control 
  1844.  
  1845.  Navigation Links 
  1846.  
  1847.       CONTINUE - SmSaveVars 
  1848.       BACK - SmPromptDlg 
  1849.       BUILT-IN FUNCTIONS 
  1850.       SECTION 2 - MiCL Programming 
  1851.       CONTENTS 
  1852.  
  1853.  
  1854. ΓòÉΓòÉΓòÉ 5.5.15. SmSaveVars( ) ΓòÉΓòÉΓòÉ
  1855.  
  1856. .SmSaveVars ( ) 
  1857.  
  1858.   SmSaveVars (  Filename, Options ) 
  1859.  
  1860.   SmSaveVars creates an ASCII text file containing assignment statements with 
  1861. the variables and values of these variables that the time that this function is 
  1862. executed.  The format of the file corresponds to the format described above for 
  1863. SmLoadVars. 
  1864.  
  1865.   The Options argument specifies whether GLOBAL, STATIC or both sets of 
  1866. variables are to be written to the file. 
  1867.  
  1868.   This command is usually performed at the end of the process in the 
  1869. "$$POST_PROCESS" command procedure. 
  1870.  
  1871.   Description for the arguments of this function follows: 
  1872.  
  1873.       Filename                 The filename of the output file.  If the 
  1874.                                filename is not fully qualified, the default 
  1875.                                directory is the directory containing the 
  1876.                                currently selected List-Of-Files. 
  1877.       Options                  Specify the type of variables and can be one or 
  1878.                                a combination of the following ( separated by 
  1879.                                the OR symbol, "|" ): GLOBAL' - process global 
  1880.                                variables and/or 'STATIC' - keyword static 
  1881.                                variables 
  1882.       result                   A success value for the function. 1= Ok. 
  1883.                                0=Error. 
  1884.  
  1885.    Example: 
  1886.  
  1887.      SmSaveVars( "VARS1.DAT", GLOBAL | STATIC )
  1888.  
  1889.  Related Topics 
  1890.  
  1891.       Pre and Post Command Sets 
  1892.       Global, Static and Local Variables 
  1893.  
  1894.  Navigation Links 
  1895.  
  1896.       CONTINUE - SmSendToEditor 
  1897.       BACK - SmRemove 
  1898.       BUILT-IN FUNCTIONS 
  1899.       SECTION 2 - MiCL Programming 
  1900.       CONTENTS 
  1901.  
  1902.  
  1903. ΓòÉΓòÉΓòÉ 5.5.16. SmSendToEditor( ) ΓòÉΓòÉΓòÉ
  1904.  
  1905. .SmSendToEditor ( ) 
  1906.  
  1907.   SmSendToEditor (  Template ) 
  1908.  
  1909.   SmSendToEditor passes the Parameter to the editor defined in the SMART setup 
  1910. options. The editor, or whatever proxy program is specified in the setup 
  1911. option, will be spawned by this command.  The argument in this command will be 
  1912. passed as an argument string to the application spawned. 
  1913.  
  1914.   If you want to pause processing at this point until the user has a chance to 
  1915. view the displayed argument, you should follow this command with the 
  1916. SmDisplayDlg, SmPromptDlg, or SmListDlg command. 
  1917.  
  1918.   Typically, the argument for an editor will be the filename, linenumber, 
  1919. column of the current keyword. 
  1920.  
  1921.   Failure to temporarily halt the processing while the editor is receiving the 
  1922. parameter from this command may create a race condition with multiple commands 
  1923. in rapid fire succession attempting to display multiple files.  The timing of 
  1924. this condition may create a system wide failure, if not just a mess of confused 
  1925. editor instances and file displays. 
  1926.  
  1927.   The use of a project ID is highly recommended in the creation of a The SMART 
  1928. Editor instance for SMART, and in the parameter of the SMART Editor 
  1929. specification. 
  1930.  
  1931.   Description for the arguments of this function follows: 
  1932.  
  1933.       Template                 A variable containing a keyword template, or a 
  1934.                                variable containing a string to be processed as 
  1935.                                a template, or a literal to be used as the 
  1936.                                argument in starting the SMART specified editor 
  1937.                                (see "Options", "SetupOptions" in the main menu 
  1938.                                of SMART.)  Note that if other parameters are 
  1939.                                specified in the Setup Panel, they will be sent 
  1940.                                in addition to the argument of this command. 
  1941.       result                   A success value for the function. 1= Ok. 
  1942.                                0=Error. 
  1943.  
  1944.    Example: 
  1945.  
  1946.      SmSendToEditor( "$LFile($LLine:$LCol)R" )
  1947.      DISPLAY = "Migrate This Keyword : " $KEY
  1948.      SmDisplayDlg( DISPLAY, OPTION,
  1949.             ~Yes | ~No | ~Abort)
  1950.      IF OPTION = "Abort" THEN TERMINATE
  1951.      IF OPTION = "NO" THEN
  1952.         SmNoMigrate()
  1953.        ELSE
  1954.         SmMigrateKeyword( $T1)
  1955.  
  1956.    Notes: 
  1957.  
  1958.    The construction of the parameter to send to the editor maybe somewhat 
  1959.  dependent upon the capabilities of the editor.  In the above example the 
  1960.  created parameter will appear in the following format indicating a fully 
  1961.  qualified file name followed by line and column number of the keyword, and a 
  1962.  designator for opening the file as read-only: 
  1963.  
  1964.      C:\MYAPP\FILE.C(123:12)R
  1965.  
  1966.  Related Topics 
  1967.  
  1968.       Use of Templates 
  1969.       Use of Dialog Functions 
  1970.       Launching the Editor 
  1971.  
  1972.  Navigation Links 
  1973.  
  1974.       CONTINUE - MiCL Instructions 
  1975.       BACK - SmSaveVars 
  1976.       BUILT-IN FUNCTIONS 
  1977.       SECTION 2 - MiCL Programming 
  1978.       CONTENTS 
  1979.  
  1980.  
  1981. ΓòÉΓòÉΓòÉ 5.6. MiCL Instructions ΓòÉΓòÉΓòÉ
  1982.  
  1983. MiCL Instructions 
  1984.  
  1985.   The following processing instructions are defined in the SMART Migration 
  1986. Command Language. 
  1987.  
  1988.     IF - THEN 
  1989.  
  1990.     ELSE 
  1991.  
  1992.     DO-END 
  1993.  
  1994.     EXIT 
  1995.  
  1996.     DEFAULT 
  1997.  
  1998.     TERMINATE 
  1999.  
  2000.     =  (Assignment) 
  2001.  
  2002.    In addition to the instructions, the following comparison operators are 
  2003. defined to be used in the decision instruction, IF-THEN. 
  2004.  
  2005.     <  (Less than) 
  2006.  
  2007.     >  (Greater than). 
  2008.  
  2009.     =  (Equal) 
  2010.  
  2011.     NOT ( used in conjunction with one of the other operators) 
  2012.  
  2013. IF - THEN - ELSE- DO - END 
  2014.  
  2015.   The "IF" instruction is used with a "THEN" instruction to make a decision. 
  2016. The command processor runs the instruction if the expression is true; for 
  2017. example: 
  2018.  
  2019.    if answer = "YES" then
  2020.      EXIT
  2021.  
  2022.   In this example, the EXIT instruction is processed only if "answer" has the 
  2023. value of "YES". 
  2024.  
  2025.   Character strings are compared character by character with a result of true 
  2026. or false depending upon the ASCII value of the first non-matching character. 
  2027.  
  2028.   You can group instructions using DO and END .  To tell the interpreter to run 
  2029. a list of instructions after the THEN instruction, use DO-END as in the 
  2030. following example: 
  2031.  
  2032.    if answer = "YES" then
  2033.      DO
  2034.       ...
  2035.       ...
  2036.       ...
  2037.      END
  2038.    else
  2039.       ...
  2040.  
  2041.   The DO and its END instruction tell the interpreter to process any 
  2042. instructions between them depending upon the comparison condition. 
  2043.  
  2044.   ELSE identifies the instruction to be run if the expression is false.  To 
  2045. tell the interpreter to select from one of two possible instructions, use: 
  2046.  
  2047.    IF expression THEN
  2048.      instruction1
  2049.    ELSE
  2050.      instruction2
  2051.  
  2052.   You could include the IF-THEN-ELSE format in a procedure like this: 
  2053.  
  2054.      IF answer = 'NO' THEN
  2055.         EXIT
  2056.       ELSE
  2057.         SmMigrateKeyword( $T1 )
  2058.  
  2059.   The comparison operators (<,>,=) along with the NOT operators can be used in 
  2060. combination with the decision instruction (IF). 
  2061.  
  2062.   Nested IF statements are only allowed if the scope of each nested if 
  2063. instruction is defined by the DO-END instruction set.  As an example: 
  2064.  
  2065.      IF OptionA = "TRUE" THEN
  2066.       DO
  2067.        IF OptionC = "TRUE" THEN
  2068.          DO
  2069.           SmDisplayDlg("OptionC is TRUE",
  2070.                   OPTION, Ok | Cancel | Abort)
  2071.           EXIT
  2072.          END
  2073.        ELSE
  2074.           SmDisplayDlg("OptionC is FALSE", OPTION,
  2075.                   Ok | Cancel | Abort)
  2076.       END
  2077.      ELSE
  2078.       DO
  2079.        SmDisplayDlg("OptionA is FALSE", OPTION,
  2080.                     Ok | Cancel | Abort)
  2081.        IF OptionB = "TRUE" THEN
  2082.           SmDisplayDlg("OptionB is TRUE", OPTION,
  2083.                     Ok | Cancel | Abort)
  2084.        ELSE
  2085.           SmDisplayDlg("OptionB is FALSE", OPTION,
  2086.                      Ok | Cancel | Abort)
  2087.       END
  2088.  
  2089.   The "IF" instruction must appear as the first word on a command coding line. 
  2090. Processing for the comparison statement stops with the "THEN" instruction.  The 
  2091. "DO" and "END" instructions must appear on separate coding lines without any 
  2092. other instruction. 
  2093.  
  2094.   The comparison expression in an IF-THEN instruction can only be a simple 
  2095. statement of the form: 
  2096.  
  2097.        item1 operator item2 
  2098.          Where: 
  2099.           item1 must be a variable 
  2100.           operator can be "<", ">", or "=" and may be preceeded by "NOT" 
  2101.           item2 must be a variable, or a literal string. 
  2102.  
  2103.    Example: 
  2104.  
  2105.      if OPTION = 'Abort' then TERMINATE
  2106.      if RESULT not = "Ok" then EXIT
  2107.  
  2108.  EXIT 
  2109.  
  2110.    The EXIT instruction terminates processing of the current command set.  The 
  2111.  EXIT statement is not required at the end of the command set, since an exit 
  2112.  condition is processed by default at the end of each command set. 
  2113.  
  2114.  DEFAULT 
  2115.  
  2116.    The DEFAULT instruction exits the current MiCL command set and reverts to 
  2117.  the Primary Migration Database instructions for processing the keyword. 
  2118.  
  2119.  TERMINATE 
  2120.  
  2121.    The TERMINATE instruction unconditionally stops the migration process, 
  2122.  immediately. 
  2123.  
  2124.  .Assignment  ( = ) 
  2125.  
  2126.    The assignment operator equates the variable to the left of the operator to 
  2127.  be equal to the value of the expression to the right.  This expression can be 
  2128.  another variable, a literal string, the result of a  SMART built-in function 
  2129.  call,  or a string formatted from a combination of literal strings and 
  2130.  variable values. 
  2131.  
  2132.    The variables in this instruction can be SMART predefined variables, or user 
  2133.  defined variables.  The user defined variables do not need declaration.  Their 
  2134.  use in an instruction automatically declares the variable. 
  2135.  
  2136.    The following examples show the use of the assignment instruction. 
  2137.  
  2138.      $Ghab = 'hab'
  2139.  
  2140.    Sets the global variable $Ghab to contain the string "hab". 
  2141.  
  2142.      $T0 = $T1
  2143.  
  2144.    Copies the template, $T1, to the current processing template $T0. 
  2145.  
  2146.      $P1 = 'hwndMenu'
  2147.  
  2148.    Set the current template parameter $P1 to contain the string "hwndMenu" 
  2149.  
  2150.      str = 'The keyword ' $KEY ' cannot be migrated.'
  2151.      SmOutputNote ( str )
  2152.  
  2153.    These two instructions create a migration note and places it in the 
  2154.  migration comments for the current keyword.  Note the concatenation of the 
  2155.  literal strings with the contents of the predefined variable $KEY, containing 
  2156.  the current keyword string. 
  2157.  
  2158.  Related Topics 
  2159.  
  2160.       Two MiCL Examples 
  2161.  
  2162.  Navigation Links 
  2163.  
  2164.       CONTINUE - Event Command Procedures 
  2165.       BACK - SmSendToEditor 
  2166.       SECTION 2 - MiCL Programming 
  2167.       CONTENTS 
  2168.  
  2169.  
  2170. ΓòÉΓòÉΓòÉ 5.7. Event Command Procedures ΓòÉΓòÉΓòÉ
  2171.  
  2172. Event Command Procedures 
  2173.  
  2174.   Each keyword in the SMART and User Migration Data Base can contain a command 
  2175. set of instructions for custom processing of the migration code required by the 
  2176. keyword.  In addition to these standard command sets, there is a special 
  2177. facility to provide you with pre and post migration event commands sets. 
  2178.  
  2179.   As an example, you may wish to prompt the user for the variable containing 
  2180. the application HAB at the start of the migration process.  You can do this by 
  2181. creating a set of commands to be processed before (pre) the migration process 
  2182. as follows: 
  2183.  
  2184.    result = SmPrompt( $Ghab, "Enter HAB variable name.", Ok | Abort )
  2185.    if result = "Abort"
  2186.      then TERMINATE
  2187.  
  2188.   In order for SMART to process this command set, the commands are entered into 
  2189. the Migration data base under the pseudo-keyword "$$PRE_PROCESS".  All 
  2190. pseudo-keywords are designated as migration event command sets and are not used 
  2191. in SMART for any other reason. 
  2192.  
  2193.   The following pseudo-keyword designators are provided for your use. 
  2194.  
  2195.       $$PRE_PROCESS            At the beginning of the migration process, 
  2196.                                before any files are processed. 
  2197.       $$POST_PROCESS           At the end of the migration process.  All 
  2198.                                globals and keyword static variables are 
  2199.                                accessible at this time. 
  2200.       $$PRE_FILE               Just before the first line of a new file is 
  2201.                                read.  The current filename is accessible in the 
  2202.                                global variable $GFILE. 
  2203.       $$POST_FILE              After the end of file is processed and the file 
  2204.                                is closed. 
  2205.  
  2206.    In the processing of Event Command sets many of the MiCL built-in functions 
  2207.  are not applicable and will not process.  Also, the preloaded variables 
  2208.  ($K..., $L..., $Pn, $Tn) and any Static variables ($S...) are not accessible. 
  2209.  
  2210.    Only the following built-in MiCL functions are available to event command 
  2211.  sets. 
  2212.  
  2213.          SmDisplayDlg ( Display_String, Option_Return, Control_Options ) 
  2214.          SmGetListName ( Return_Variable ) 
  2215.          SmGetListPath ( Return_Variable ) 
  2216.          SmGetSmartPath ( Return_Variable ) 
  2217.          SmListDlg ( Display_String,  Edit_String, Option_Return, 
  2218.       String_Return_Variable, Filename ) 
  2219.          SmLoadVars ( Filename ) 
  2220.          SmPromptDlg ( Display_String, Edit_String, Option_Return, 
  2221.       String_Return_Variable, Control_Options ) 
  2222.          SmSaveVars ( Filename, [STATIC | GLOBAL] ) 
  2223.          SmSendToEditor ( Template ) 
  2224.  
  2225.    The Pre and Post Process command sets can best be utilized to load or save 
  2226.  the process variables with the functions: 
  2227.  
  2228.          SmLoadVars ( Filename ) 
  2229.          SmSaveVars ( Filename, [STATIC | GLOBAL] ) 
  2230.  
  2231.    These event command sets can also be utilized to provide run-time 
  2232.  interaction with the user to obtain variable names or run options that can 
  2233.  easily be stored in process global variables for use by any keyword command 
  2234.  set during the process run. 
  2235.  
  2236.    Interactive dialogs can be created and used with the following built-in 
  2237.  functions: 
  2238.  
  2239.          SmDisplayDlg ( Display_String, Option_Return, Control_Options ) 
  2240.          SmListDlg ( Display_String,  Edit_String, Option_Return, 
  2241.       String_Return_Variable, Filename ) 
  2242.          SmPromptDlg ( Display_String, Edit_String, Option_Return, 
  2243.       String_Return_Variable, Control_Options ) 
  2244.  
  2245.  Related Topics 
  2246.  
  2247.       Preset Variables 
  2248.       Pre and Post Command Sets 
  2249.       Global, Static and Local Variables 
  2250.  
  2251.  Navigation Links 
  2252.  
  2253.       CONTINUE - Programming Notes and Tips 
  2254.       BACK - MiCL Instructions 
  2255.       SECTION 2 - MiCL Programming 
  2256.       CONTENTS 
  2257.  
  2258.  
  2259. ΓòÉΓòÉΓòÉ 5.8. Programming Notes and Tips ΓòÉΓòÉΓòÉ
  2260.  
  2261. Programming Notes and Tips 
  2262.  
  2263.          MiCL Basics 
  2264.          Preset Variables 
  2265.          Two MiCL Examples 
  2266.          Pre and Post Command Sets 
  2267.          Use of Templates 
  2268.          Use of Dialog Functions 
  2269.          Migration Control 
  2270.          Migration Notes and Comments 
  2271.          Global, Static and Local Variables 
  2272.          String and Variable Evaluation 
  2273.          Launching the Editor 
  2274.          Testing MiCL Command Sets 
  2275.  
  2276.  Navigation Links 
  2277.  
  2278.       CONTINUE - MiCL Basics 
  2279.       BACK - Event Command Procedures 
  2280.       SECTION 2 - MiCL Programming 
  2281.       CONTENTS 
  2282.  
  2283.  
  2284. ΓòÉΓòÉΓòÉ 5.8.1. MiCL Basics ΓòÉΓòÉΓòÉ
  2285.  
  2286. MiCL Basics 
  2287.  
  2288.   In general, the SMART Migration Command Language defines a flexible set of 
  2289. commands to be used in the custom migration of identified keywords which may be 
  2290. encountered in a source language.  The exception to this is the Pre and Post 
  2291. processing command sets triggered at specific events during the migration 
  2292. process. 
  2293.  
  2294.   Once a keyword to be migrated is identified in the source code SMART accesses 
  2295. the currently selected Migration database for records related to the keyword 
  2296. containing: short comments, long comments, templates, prototypes, sample code, 
  2297. commands and references. 
  2298.  
  2299.   A command set consists of a number of SMART Migration Command Language 
  2300. instructions, and built-in function calls to affect the specific migration of 
  2301. an encountered keyword. 
  2302.  
  2303.   If no commands are programmed for a specific keyword, then the migration is 
  2304. processed using the default actions. Category 000 keywords are left unaffected. 
  2305. Category 010 keywords require a simple literal string replacement.  These 
  2306. keywords will be processed automatically without commands and will have the 
  2307. detected keyword replaced by the template string provided in the migration 
  2308. database without evaluation. 
  2309.  
  2310.   Category 020 and above are good candidates for SMART command processing.  If 
  2311. there are no commands available in the migration database, SMART will simply 
  2312. output the migration code as defined in the options settings for each category. 
  2313. Typically this will simply be a set of migration comments inserted in the 
  2314. output source code, 
  2315.  
  2316.   A keyword command set can be as simple as an output of the template into the 
  2317. migration code stream, along with the arguments of the keyword function 
  2318. inserted into the migrated output. 
  2319.  
  2320.    /* Dos Delete - OS/2 1.3 to OS/2 2.1    */
  2321.    /* Second argument is deleted       */
  2322.    /* Template : DosDelete( $P1 )       */
  2323.    SmMigrateKeyword(T1)
  2324.  
  2325.   In this example the template for this keyword as coded in the migration table 
  2326. is automatically evaluated in the SmMigrateKeyword function replacing the 
  2327. argument of the output keyword API function call with the first argument of the 
  2328. input keyword function.  The results of this simple migration follow. 
  2329.  
  2330.   Input source code: 
  2331.  
  2332.    DosDelete( szTheFile, 0L );
  2333.  
  2334.   Output migrated source code: 
  2335.  
  2336.    DosDelete( szTheFile );
  2337.  
  2338. Navigation Links 
  2339.  
  2340.       CONTINUE - Preset Variables 
  2341.       BACK - NOTES and TIPS 
  2342.       NOTES and TIPS 
  2343.       SECTION 2 - MiCL Programming 
  2344.       CONTENTS 
  2345.  
  2346.  
  2347. ΓòÉΓòÉΓòÉ 5.8.2. Preset Variables ΓòÉΓòÉΓòÉ
  2348.  
  2349. Preset Variables 
  2350.  
  2351.   The processing of the keyword commands starts with a number of predefined 
  2352. variables initialized and available to the commands. 
  2353.  
  2354.   Process global variables ($Gxxxxxxxx) can be set in any command set and are 
  2355. available to all keyword commands throughout the current migration process. 
  2356.  
  2357.   Keyword static variables ($Sxxxxxxxx) are variables that are local to each 
  2358. keyword, but which retain their value throughout the migration process.  You 
  2359. can prompt, or otherwise save a value the first time a keyword is processed to 
  2360. use this value throughout the remaining process. 
  2361.  
  2362.   At the end of a process run you may save all of the Global and Static 
  2363. variable values into a hard file to be reloaded at the beginning of another 
  2364. migration run. 
  2365.  
  2366.   The keyword information variables, $K... contain information about the 
  2367. keyword and are available to the command set.  The source code file and line 
  2368. information is available in the preset variables $L... . 
  2369.  
  2370.   If the keyword is a function call, the arguments of this call are stored in 
  2371. $P1...$Pn, with the number of arguments stored in the variable $PCNT. 
  2372.  
  2373.   Any templates that are in the migration database for the current keyword are 
  2374. available in the predefined variables $T1...$Tn, with the number of available 
  2375. templates stored in $TCNT. 
  2376.  
  2377.   The following is an example of a keyword template: 
  2378.  
  2379.    WinMessageBox(HWND_DESKTOP, $GhFrame, $P3, $P2, 0, ?Options)
  2380.  
  2381.   Note that the Global variable $GhFrame has been previously initialized.  The 
  2382. two arguments $P3 and $P2 come from the input keyword function call arguments 
  2383. (automatically).  The last argument, ?Options is a local variable that been set 
  2384. in prior statements before the output instruction for this template. 
  2385.  
  2386.   The predefined variable $KIND tells you if  an API keyword functional call is 
  2387. embedded in an expression in the source code.  This value is important to 
  2388. determine whether a function call can be removed (if standing alone), or can be 
  2389. set to some static return value (if the return value is used as an argument), 
  2390. or simply cannot be migrated and must have a note attached saying so. 
  2391.  
  2392. Navigation Links 
  2393.  
  2394.       CONTINUE - Two MiCL Examples 
  2395.       BACK - MiCL Basics 
  2396.       NOTES and TIPS 
  2397.       SECTION 2 - MiCL Programming 
  2398.       CONTENTS 
  2399.  
  2400.  
  2401. ΓòÉΓòÉΓòÉ 5.8.3. Two MiCL Examples ΓòÉΓòÉΓòÉ
  2402.  
  2403. Two MiCL Examples 
  2404.  
  2405.   In the following example, a single keyword function call will generate 
  2406. several lines of migrated output. 
  2407.  
  2408.   The keyword is "SetParent"  in a Win 3.1 which appears in the source code as 
  2409. follows: 
  2410.  
  2411.      SetParent(hwnd, hwndParent)
  2412.  
  2413.   The SMART migration table templates for this keyword are: 
  2414.  
  2415.      .Template =$P2 = WinQueryWindow ($P1, QW_PARENT);
  2416.           =WinSetParent ($P1, $P2, TRUE);
  2417.           =if (($P2 != HWND_DESKTOP) &&
  2418.           =  ($P2 != HWND_OBJECT))
  2419.           =    WinSetOwner ($P1, $P2)
  2420.           =  else
  2421.           =    WinSetOwner ($P1, (HWND)0);
  2422.  
  2423.   The command set for the migration of this keyword follows: 
  2424.  
  2425.      /* Replace source code for SetParent - Category 030 */
  2426.      IF $KIND = "TRUE" THEN
  2427.       DO
  2428.         SmSendToEditor( "$LFILE($LLINE:$LCOL)R" )
  2429.         DISPLAY = "Verify removal and replacement for keyword: " $KEY
  2430.         SmDisplay( DISPLAY, OPTION, ~Yes | ~No | ~Abort )
  2431.         IF OPTION = "Abort" THEN TERMINATE
  2432.         IF OPTION = "Yes" THEN
  2433.          DO
  2434.            SmRemove(LINE)
  2435.            SmOutputLine( $T1 )
  2436.            SmOutputLine( $T2 )
  2437.            SmOutputLine( $T3 )
  2438.            SmOutputLine( $T4 )
  2439.            SmOutputLine( $T5 )
  2440.            SmOutputLine( $T6 )
  2441.            SmOutputLine( $T7 )
  2442.            SmNoMigrate( )
  2443.            SmNoComment( ALL )
  2444.            NOTE = "Source line removed and code replaced for:" $KEY
  2445.            SmOutputNote( NOTE )
  2446.          END
  2447.       END
  2448.      ELSE
  2449.       DO
  2450.         string = "*** Unable to migrate : " $KEY
  2451.         SmOutputNote( string )
  2452.         SmOutputNote("*** Multi-line migration is embedded.")
  2453.         SmNoMigrate( )
  2454.       END
  2455.  
  2456.   In this example the command processing checks to see if the keyword is 
  2457. standing alone. If the answer is true, then the source code at the point of the 
  2458. keyword is sent to the editor for the user to view. 
  2459.  
  2460.   Next a display dialog confirms replacement of the code.  If the user responds 
  2461. "Ok" then the seven output templates are used to generate the migrated output 
  2462. code,  with the template variables replaced by the values of the input 
  2463. arguments. 
  2464.  
  2465.   The standard output comments were supressed and a note was inserted in this 
  2466. migration to indicate the code replacement. 
  2467.  
  2468.   The migrated code created from this command set is shown below: 
  2469.  
  2470.    // SetParent(hwnd, hwndParent );              SM$:O
  2471.    hwndParent = WinQueryWindow (hwnd, QW_PARENT);      // SM$:M1
  2472.    WinSetParent (hwnd, hwndParent, TRUE);          // SM$:M1
  2473.    if ((hwndParent != HWND_DESKTOP) &&           // SM$:M1
  2474.      (hwndParent != HWND_OBJECT))             // SM$:M1
  2475.       WinSetOwner (hwnd, hwndParent)           // SM$:M1
  2476.      else                         // SM$:M1
  2477.       WinSetOwner (hwnd, (HWND)0);            // SM$:M1
  2478.     // Source line removed and code replaced for: SetParent  SM$:I
  2479.  
  2480.   In the next example you wish to migrate a user function and modify the 
  2481. calling sequence every place that it appears by inserting a new argument at the 
  2482. front of the argument list.  The user is to be prompted the first time that the 
  2483. keyword is encountered, but the response will be saved for all other 
  2484. occurrences. 
  2485.  
  2486.   The keyword is "MyMessageBox" in the form of: 
  2487.  
  2488.       MyMessageBox( szString, lOptions );
  2489.  
  2490.   The template for this migration is: 
  2491.  
  2492.       MyMessageBox( $Shwnd1, $P1, $P2 )
  2493.  
  2494.   The command set follows: 
  2495.  
  2496.    IF $Shwnd1 = "" THEN
  2497.      DO
  2498.       result = SmPrompt( "Enter variable for MyMessageBox argument 1.",
  2499.                "hwnd", option, $Shwnd1, OK | Abort)
  2500.       IF option = 'Abort' THEN TERMINATE
  2501.      END
  2502.    SmMigrateKeyword( T1 )
  2503.  
  2504.   In the example above the static variable $Shwnd1 was checked for a value and 
  2505. if none was present the user was prompted for the variable name.  Furthermore, 
  2506. if the user terminated out of the entry panel then the process was stopped, 
  2507. otherwise the migration was completed with the keyword template using the value 
  2508. of the static variable $Shwnd1. 
  2509.  
  2510. Navigation Links 
  2511.  
  2512.       CONTINUE - Pre and Post Command Sets 
  2513.       BACK - Preset Variables 
  2514.       NOTES and TIPS 
  2515.       SECTION 2 - MiCL Programming 
  2516.       CONTENTS 
  2517.  
  2518.  
  2519. ΓòÉΓòÉΓòÉ 5.8.4. Pre and Post Command Sets ΓòÉΓòÉΓòÉ
  2520.  
  2521. Pre and Post Command Sets 
  2522.  
  2523.   The preprocess command set can be used to prompt for process run options, 
  2524. global variables that may be used through the migration process, and used to 
  2525. load previous data from an earlier run.  For obvious reasons, many of the 
  2526. keyword related built-in functions are not available for use in the event 
  2527. command sets. 
  2528.  
  2529.   However, with the use of the MiCL interactive dialog functions you will be 
  2530. able to set process global variables at run time by prompting the user. 
  2531.  
  2532.   The following commands provide a good example for the preprocess event 
  2533. command set. These commands are coded into a pseudo-keyword structure in the 
  2534. migration table. 
  2535.  
  2536.   .Keyword =999 000 999 $$PRE_PROCESS
  2537.   .SComment=Preprocess Command set
  2538.   .Command = SmGetListPath( LISTPATH )
  2539.       = $GVARS = LISTPATH "\VARS1.DAT"
  2540.       = SmPromptDlg( "Enter filename for loading process variables:",
  2541.       =       $GVARS, OPTION, $GVARS, ~Ok | ~Abort )
  2542.       = if OPTION = "Abort" then terminate
  2543.       = SmLoadVars( $GVARS )
  2544.       = if $GHAB = "" then
  2545.       =       $GHAB = "hab"
  2546.       = SmPromptDlg( "Enter application HAB variable name:",
  2547.       =       $GHAB, OPTION, $GHAB, ~Ok | ~Abort )
  2548.       = if OPTION = "Abort" then terminate
  2549.  
  2550.   In the example above, the first order of business is to get the current 
  2551. List-of-Files directory path and create a default filename for the process 
  2552. variables file. 
  2553.  
  2554.   Once the user has accepted this filename or entered another name in the edit 
  2555. field, then the function is executed to load the variables from the specified 
  2556. file. 
  2557.  
  2558.   Next a check is made for the loaded global variable $GHAB to see if it has a 
  2559. valid entry. Note that MiCL initializes a new variable with a null string. 
  2560. Variables are created when referenced.  Therefore, when the variable $GHAB was 
  2561. checked in the IF-THEN instruction, the variable was created with a null entry 
  2562. if the variable did not previously exist. 
  2563.  
  2564.   In this example, if the global variable was null then we set the value to our 
  2565. default value "hab". 
  2566.  
  2567.   Finally, a prompt dialog is created to allow the user to enter the string for 
  2568. the application HAB variable or accept the one displayed. 
  2569.  
  2570.   The Post-Process command set allows you the opportunity to execute any 
  2571. functions that you may need at the end of the migration process after all of 
  2572. the migration files have been processed and closed.  Typically this may consist 
  2573. of simply saving the static and global variables from the current migration 
  2574. run.  Following is a sample of a typical post-processing command set. 
  2575.  
  2576.   .Keyword =999 000 999 $$POST_PROCESS
  2577.   .SComment=Post-process Command set
  2578.   .Command = if $GVARS = "" then
  2579.       =  do
  2580.       =    SmGetListPath( LISTPATH )
  2581.       =    $GVARS = LISTPATH "\VARS1.DAT"
  2582.       =  end
  2583.       = SmPromptDlg( "Enter filename for storing process variables:",
  2584.       =       $GVARS, OPTION, $GVARS, ~Ok | ~Abort )
  2585.       = if OPTION = "Abort" then terminate
  2586.       = SmSaveVars( STATIC | GLOBAL )
  2587.  
  2588.   Note in this example we took advantage of the fact that in the preprocess 
  2589. command set we stored the filename of the variables in a global variable, 
  2590. "$GVARS".  Now at the end of the process we can access this stored filename and 
  2591. use it as the default entry item in a prompt to the user. 
  2592.  
  2593.   Recalling that the first button in the SmDisplayDlg, SmPromptDlg, and the 
  2594. SmListDlg respond to the keyboard "Enter" key, while the second button responds 
  2595. to the "Esc" key. 
  2596.  
  2597.   Since we have placed the natural default filename in the entry field of the 
  2598. prompt, the user can complete the process with this filename by simply pressing 
  2599. the "Enter" key. 
  2600.  
  2601. Related Topics 
  2602.  
  2603.       Global, Static and Local Variables 
  2604.  
  2605.  Navigation Links 
  2606.  
  2607.       CONTINUE - Use of Templates 
  2608.       BACK - Two MiCL Examples 
  2609.       NOTES and TIPS 
  2610.       SECTION 2 - MiCL Programming 
  2611.       CONTENTS 
  2612.  
  2613.  
  2614. ΓòÉΓòÉΓòÉ 5.8.5. Use of Templates ΓòÉΓòÉΓòÉ
  2615.  
  2616. Use of Templates 
  2617.  
  2618.   Use of a template, along with the MiCL built-in command SmMigrateKeyword is a 
  2619. simple and effective way to migrate an API keyword when the arguments of the 
  2620. call have be changed. 
  2621.  
  2622.   With a template for an API migration you have the ability to reorder the 
  2623. arguments, delete any arguments, insert new arguments.  The new arguments may 
  2624. be a literal string, the contents of a user prompted variable, or the user 
  2625. selected return from a list of possible arguments from the SmListDlg dialog. 
  2626.  
  2627.   The argument can even be the assignment return variable from the source code 
  2628. that may exit in the form of: 
  2629.  
  2630.    sReturn = Fcn( Arg1, Arg2, Arg3);
  2631.  
  2632.   The mechanism for this migration maneuver begins with the predefined 
  2633. variables that are available at the beginning of the command set.  Each 
  2634. argument of the API keyword function call in the source code is set to the 
  2635. variables $P1-$Pn.  The assignment return variable $KRTN contains the variable 
  2636. name of the function return assignment if any exists.  All templates found for 
  2637. the current keyword are available in the predefined variables $T1-$Tn. 
  2638.  
  2639.   A template is a coding string that is loaded into the migration table 
  2640. dictionary with a tag of ".Template".  The template should be coded exactly as 
  2641. it will appear to replace the keyword in the source code, or appear as a 
  2642. generated source code line using the SmMigrateKeyword built-in function.  Any 
  2643. spacing, literals, special syntax characters and any other item that is to 
  2644. appear in the output should be placed in the template. 
  2645.  
  2646.   The power and flexibility of the template comes from the use of any variables 
  2647. that you may place in the template.  During the evaluation of the template in 
  2648. the built-in functions SmMigrateKeyword or SmOutputLine, any variables that 
  2649. start with "$" or "? ".  This will include any process Global or keyword Static 
  2650. variables along with predefined variables, and any keyword local variable that 
  2651. begins with "$" or "?". 
  2652.  
  2653.   Example: 
  2654.  
  2655.   Windows source statement: 
  2656.  
  2657.    bChild = IsChild (hWndParent, hWndChild);
  2658.  
  2659.   Migration Table code: 
  2660.  
  2661.    .Template =WinIsChild ($P2, $P1)
  2662.    .Command=SmMigrateKeyword( $T1)
  2663.  
  2664.    Migrate output code: 
  2665.  
  2666.      bChild = WinIsChild (hWndChild, hWndParent);
  2667.  
  2668.   Note in the simple example above that the parameters of the Win keyword API 
  2669. "IsChild" are reversed in their appearance in the OS/2 migrated code.  This was 
  2670. accomplished by simply stating the format of the output in the keyword template 
  2671. coded into the migration table, and then declaring the built-in function 
  2672. SmMigrateKeyword() in the command set. 
  2673.  
  2674.   The following hypothetical example makes use of the $KRTN variable and a 
  2675. multiple output migration coding lines. 
  2676.  
  2677.   Win statement: 
  2678.  
  2679.    sCount = ButtonCount( hWnd, 0L);
  2680.  
  2681.   Migration Table code: 
  2682.  
  2683.    .Template=HWND hwndDlg = WinGetDialogFocus( $P1 );
  2684.         =WinGetButtonCount( HWND_DESKTOP, hwndDlg, &$KRTN );
  2685.    .Command =IF $KIND = "TRUE" THEN
  2686.         =  DO
  2687.         =   SmSendToEditor( "$LFILE($LLINE:$LCOL)R" )
  2688.         =   DISPLAY = "Verify  code replacement for keyword: " $KEY
  2689.         =   SmDisplay( DISPLAY, OPTION, ~Yes | ~No | ~Abort )
  2690.         =   IF OPTION = "Abort" THEN TERMINATE
  2691.         =   IF OPTION = "Yes" THEN
  2692.         =     DO
  2693.         =      SmRemove(LINE)
  2694.         =      SmOutputLine( $T1 )
  2695.         =      SmOutputLine( $T2 )
  2696.         =     END
  2697.         =  END
  2698.         =ELSE
  2699.         =  DO
  2700.         =   string = "*** Unable to migrate : " $KEY
  2701.         =   SmOutputNote( string )
  2702.         =   SmOutputNote("*** Multi-line migration is embedded.")
  2703.         =   SmNoMigrate( )
  2704.         =  END
  2705.  
  2706.   Migrated Output Code: 
  2707.  
  2708.    HWND hwndDlg = WinGetDialogFocus( hWnd );
  2709.    WinGetButtonCount( HWND_DESKTOP, hwndDlg, &sCount);
  2710.  
  2711.   There are a couble of important items to note in this example. 
  2712.  
  2713.   As in previous examples when a line of code is to be removed,  the code is 
  2714. displayed and the user is requested to verify the removal.  This will prevent 
  2715. code removal under unusual coding syntax situations which may garble the 
  2716. output. 
  2717.  
  2718.   Predefined variables are used in both templates, including the return 
  2719. variable $KRTN.  The second argument in the input source "0L" was not needed, 
  2720. and was discarded by not specifying the predefined argument variable $P2 in 
  2721. either of the templates.  You may also not that a constant "HWND_DESKTOP" was 
  2722. inserted in the second template. 
  2723.  
  2724. Related Topics 
  2725.  
  2726.       Preset Variables 
  2727.       Global, Static and Local Variables 
  2728.  
  2729.  Navigation Links 
  2730.  
  2731.       CONTINUE - Use of Dialog Functions 
  2732.       BACK - Pre and Post Commands 
  2733.       NOTES and TIPS 
  2734.       SECTION 2 - MiCL Programming 
  2735.       CONTENTS 
  2736.  
  2737.  
  2738. ΓòÉΓòÉΓòÉ 5.8.6. Use of Dialog Functions ΓòÉΓòÉΓòÉ
  2739.  
  2740. Use of Dialog Functions 
  2741.  
  2742.   Use of the built-in dialog functions SmDisplayDlg , SmPromptDlg, SmListDlg 
  2743. can enable you to create a great deal of interactive and expert-like 
  2744. functionality in the migration process. 
  2745.  
  2746.   These three dialog functions provide a great deal of flexibility while 
  2747. allowing the user to select options and provide run-time information where user 
  2748. interaction, verification and choice is required. 
  2749.  
  2750.   All three dialogs halt the migration process and wait for user response.  In 
  2751. conjunction with the SmSendToEditor , you will have the opportunity to display 
  2752. the source code at the point of the keyword encounter and allow the user to 
  2753. browse the source code to make the selection requested of the dialog. 
  2754.  
  2755.   The three dialog functions all display information, wait for user response, 
  2756. and return the response back to the command set program.  In each dialog, 
  2757. however, the capabilities are quite different. 
  2758.  
  2759. SmDisplayDlg 
  2760.  
  2761.   SmDisplayDlg is a type of message box.  The arguments of the function call 
  2762. specify the message to be displayed, a select return variable and a rather 
  2763. unique way to specify up to four buttons to be displayed. 
  2764.  
  2765.   The buttons specification depart quite differently from the WinMessageBox 
  2766. call in OS/2 Presentation Manager Programming.  In MiCL you simply specify the 
  2767. ID on each of up to four buttons.  The ID will appear on the button exactly as 
  2768. specified.  You may include a tilde (~) character preceding any character of 
  2769. the button ID to designate an accelerator key for the button. 
  2770.  
  2771.   The first button in the specification responds to the "Enter" key and the 
  2772. second button responds to the "Esc" key. 
  2773.  
  2774.   When the user presses on of the buttons created for this dialog, the dialog 
  2775. will terminate and the ID string of the button pressed will be returned as the 
  2776. value of the select return variable.  At this point you may compare the value 
  2777. of the select return variable with any one of the string IDs to determine 
  2778. appropriate action based on the selection.  Note that the button string ID 
  2779. returned does not include any tilde which may have been specified as an 
  2780. accelerator. 
  2781.  
  2782.   One other nice feature for each of the three dialogs is their placement 
  2783. recall.  If the user moves the placement of any one of the dialogs on the 
  2784. desktop, subsequent creation of the same type of dialog will appear in the 
  2785. location last positioned.  In this manner you have the opportunity to position 
  2786. the dialogs and the editor to best suit your needs during the migration 
  2787. process. 
  2788.  
  2789.   Let's look at an example of the display dialog. 
  2790.  
  2791.    .Command =SmSendToEditor( "$LFILE($LLINE:$LCOL)R" )
  2792.         =DISPLAY = "Verify  code replacement for keyword: " $KEY
  2793.         =SmDisplay( DISPLAY, OPTION, ~Yes | ~No | ~Abort )
  2794.         =IF OPTION = "Abort" THEN TERMINATE
  2795.         =IF OPTION = "Yes" THEN
  2796.         =   ...
  2797.  
  2798.   Note how the three buttons in the above dialog were specified.  The button 
  2799. IDs need not be placed in quotes.  The IDs will appear case sensitive exactly 
  2800. as they are specified. 
  2801.  
  2802.   The variable "OPTION" was used to receive the returned response. 
  2803.  
  2804. SmPromptDlg 
  2805.  
  2806.   While SmDisplayDlg can be used as a type of message box, SmPromptDlg is an 
  2807. entry panel dialog.  A prompt message string is specified in the arguments of 
  2808. the call to create this dialog. 
  2809.  
  2810.   In addition to the prompt string, the other arguments specify the initial 
  2811. entry string, the entry return variable, the button return string and the 
  2812. buttons specification. 
  2813.  
  2814.   The initial entry string provides a highlighted default entry for the user. 
  2815.  
  2816.   The entry return variable will contain the user's entry string at the 
  2817. termination of the dialog panel. 
  2818.  
  2819.   The button return variable and the buttons specification operate identically 
  2820. as in the SmDisplayDlg described above. 
  2821.  
  2822.   The following example of the SmPromptDlg function points to a good use of the 
  2823. keyword static variable to recall the previous user entry to be used as the 
  2824. current initial entry string as the dialog is initialized. 
  2825.  
  2826.      IF $Shab = "" THEN $Shab = "hab"
  2827.      RTN =  SmPromptDlg("Please enter the variable name used for HAB",
  2828.               $Shab, OPTION, $Shab, ~Ok | ~Cancel |  ~Abort )
  2829.      IF OPTION = "ABORT" THEN TERMINATE
  2830.  
  2831.   In this example the keyword static variable $Shab is used to contain the 
  2832. variable name used for the application anchor block.  If this static variable 
  2833. is null and has never been set, it is initialized to "hab". 
  2834.  
  2835.   Next note that both the initial edit string argument and the entry return 
  2836. arguments both use this same static variable.  Using this technique in 
  2837. SmPromptDlg will provide the user with their prior entry as an initial default 
  2838. in the current prompt. 
  2839.  
  2840.   You should note two poor techniques in the coding of the command set in the 
  2841. above example. There is no display of the source code immediately preceding the 
  2842. prompt dialog.  The user will not know where this prompt is referenced in the 
  2843. source code. 
  2844.  
  2845.   The second coding error is not providing the keyword in the display of the 
  2846. prompt.  By using The SMART Editor as the SMART editor, and sending the 
  2847. file/line/column_number to the editor will automatically highlight the 
  2848. referenced keyword.  However, it is a good programming technique to also 
  2849. identify the name of the keyword in the display or prompt message.  Go back and 
  2850. review the previous example for the SmDisplayDlg function. 
  2851.  
  2852. SmListDlg 
  2853.  
  2854.   The interactive dialog panel created with SmListDlg presents a number of 
  2855. unique capabilities. 
  2856.  
  2857.   Essentially this is a user maintainable, item selectable list box.  The list 
  2858. box is loaded from items contained in the file specified in the argument of the 
  2859. call to this function.  With the controls on this dialog panel, the user may 
  2860. select one of the list box items, or type a new entry to be returned to the 
  2861. command program and saved in the file for subsequent use. 
  2862.  
  2863.   The buttons on this panel, unlike the other two dialog functions, are fixed 
  2864. and not programmable. 
  2865.  
  2866.   The list of items to be loaded can be prepared from a simple text editor with 
  2867. one item per line of the file. 
  2868.  
  2869.   The user can add items, or delete any item in the list.  Double clicking on 
  2870. any list box item will automatically make the selection and terminate the 
  2871. dialog.  The item selected will be returned to the command program as the value 
  2872. of the selection return variable. 
  2873.  
  2874.   The following example demonstrates the use of the SmListDlg. 
  2875.  
  2876.      SmSendToEditor( "$LFile($LLine:$LCol)R" )
  2877.      SmListDlg("Select the choice for HANDLE replacement",
  2878.            $Shandle, OPTION, $Shandle, "HANDLE.DAT" )
  2879.      IF OPTION = "Terminate" THEN TERMINATE
  2880.      IF OPTION = "Cancel" THEN
  2881.       DO
  2882.         SmNoMigrate
  2883.         EXIT
  2884.       END
  2885.      SmMigrateKeyword( $T1 )
  2886.  
  2887.   In this example the file "HANDLE.DAT" contains the following entries: 
  2888.  
  2889.          HWND 
  2890.          PVOID 
  2891.          LHANDLE 
  2892.          CHAR * 
  2893.  
  2894.    This list box, dialog selection panel is best utilized where a combination 
  2895.  of an entry field is combined with a list of multiple selectable items is 
  2896.  needed.  It provides a user an effective opportunity to view the source code 
  2897.  at the point of keyword encounter and select one of several templates or other 
  2898.  migration options displayed in this panel. 
  2899.  
  2900.  Related Topics 
  2901.  
  2902.       Launching the Editor 
  2903.  
  2904.  Navigation Links 
  2905.  
  2906.       CONTINUE - Migration Control 
  2907.       BACK - Use of Templates 
  2908.       NOTES and TIPS 
  2909.       SECTION 2 - MiCL Programming 
  2910.       CONTENTS 
  2911.  
  2912.  
  2913. ΓòÉΓòÉΓòÉ 5.8.7. Migration Control ΓòÉΓòÉΓòÉ
  2914.  
  2915. Migration Control 
  2916.  
  2917.   General migration control is achieved with the built-in MiCL functions 
  2918. SmIgnoreKeyword( ), SmNoMigrate( ),  along with SmMigrateKeyword( ) and 
  2919. SmRemove( ). 
  2920.  
  2921.   SmIgnoreKeyword( ) will cause the processing to skip over the encountered 
  2922. keyword, just as if it did not appear in the migration table.  The original 
  2923. source code stays intact and no comments or notes are inserted in the output 
  2924. stream.  Essentially this acts like the keyword appeared in an Exclude Keyword 
  2925. file, except that this function is programmatic and can be executed depending 
  2926. upon run time conditions. 
  2927.  
  2928.   As an example, it may be necessary to process a keyword by first displaying 
  2929. the source code at the keyword encountered and then asking the user to process 
  2930. the keyword or skip this encounter.  If the user responds with "Skip", then the 
  2931. MiCL command can execute the SmIgnoreKeyword( ) function to skip the processing 
  2932. of the keyword.  The output remains intact and will appear as if the keyword 
  2933. was not encountered.  The following code demonstrates this example: 
  2934.  
  2935.    .Command =SmSendToEditor( "$LFILE($LLINE:$LCOL)R" )
  2936.         =DISPLAY = "Verify migration for keyword: " $KEY
  2937.         =SmDisplay( DISPLAY, OPTION, ~Yes | ~Skip | ~Abort )
  2938.         =IF OPTION = "Abort" THEN TERMINATE
  2939.         =IF OPTION = "Yes" THEN
  2940.         =   SmMigrateKeyword( $T1 )
  2941.         =ELSE
  2942.         =   SmIgnoreKeyword( )
  2943.  
  2944.   SmNoMigrate(  ) will cause the process to go through all of the migration 
  2945. steps, except that the keyword will appear in the output exactly as it did in 
  2946. the source code input, with no change. 
  2947.  
  2948.   In this case the original code will appear untouched, but all migration 
  2949. comments and any note generated will appear in the output code. (Note: in 
  2950. comparison, SmIgnoreKeyword will suppress all comments and notes). 
  2951.  
  2952.   This function can be used where the migration was exited during the MiCL 
  2953. command set processing and the migration could not be performed and was left to 
  2954. the user. 
  2955.  
  2956.   If you simply "EXIT"  the command set without executing SmMigrateKeyword, or 
  2957. SmNoMigrate, then the keyword (with all arguments in the case of an API 
  2958. keyword) will be left out of the output code.  This may confuse the user to see 
  2959. part of the source code left blank.  You may prefer to execute SmNoMigrate and 
  2960. place a note to the user in the output code.  An example of SmNoMigrate 
  2961. follows: 
  2962.  
  2963.   The source code appears as follows: 
  2964.  
  2965.      if (DeleteMenu (hMenu, 2, MF_BYPOSITION) )
  2966.        MenuProcess(hMenu);
  2967.  
  2968.   The migration table code: 
  2969.  
  2970.   .Template =SHORT sID = (SHORT)WinSendMsg ( $P1, MM_ITEMIDFROMPOSITION,
  2971.        =        MPFROMSHORT (2), MPVOID)
  2972.        =  WinSendMsg ( $P1, MM_DELETEITEM, MPFROM2SHORT(sID,FALSE),
  2973.        =        PVOID);
  2974.   .Command  =if $KIND = "TRUE" then
  2975.        =  do
  2976.        =    SmMigrateKeyword( $T1 )
  2977.        =    SmOutputLine( $T2 )
  2978.        =  end
  2979.        =else
  2980.        =  do
  2981.        =    SmNoMigrate()
  2982.        =    DISPLAY = "** No Migration. Embedded Keyword: " $KEY
  2983.        =    SmOutputNote( DISPLAY )
  2984.        =  end
  2985.  
  2986.   The resulting output code will appear as follows: 
  2987.  
  2988.      if (DeleteMenu (hMenu, 2, MF_BYPOSITION) )
  2989.        MenuProcess(hMenu);
  2990.      // ** No Migration. Embedded Keyword: DeleteMenu   SM$:I
  2991.      //                          SM$:C
  2992.      // DeleteMenu  - Cat:030 Type:010 Area:280      SM$:K
  2993.      // Replace with WinSendMsg and MM_DELETEITEM     SM$:S
  2994.  
  2995. Navigation Links 
  2996.  
  2997.       CONTINUE - Migration Notes and Comments 
  2998.       BACK - Use of Dialogs 
  2999.       NOTES and TIPS 
  3000.       SECTION 2 - MiCL Programming 
  3001.       CONTENTS 
  3002.  
  3003.  
  3004. ΓòÉΓòÉΓòÉ 5.8.8. Migration Notes and Comments ΓòÉΓòÉΓòÉ
  3005.  
  3006. Migration Notes and Comments 
  3007.  
  3008.   There are two MiCL built-in functions that control the output of migration 
  3009. comments and notes.  These are SmNoComment( ) and SmOutputNote( ). 
  3010.  
  3011.   Migration comments come from the migration table coded under the tags: 
  3012. SComment, LComment, Template, Prototype, and Sample.  The user has control over 
  3013. the suppression of any of these comments in the migration options settings.  In 
  3014. addition to the user control, the MiCL function call can programmatically 
  3015. suppress any of these comments by specifying the comment tag to be suppressed 
  3016. in the argument of this call. 
  3017.  
  3018.   SmOutputNote( ) places a note created in a MiCL Command set in the output 
  3019. stream under the migrated code.  Typically these notes are used to advise the 
  3020. user of some alternative action performed during the execution of the command 
  3021. set based upon the user response to a selected option.  These notes are placed 
  3022. in comments and are tagged with "SM$:I". 
  3023.  
  3024.   With the combinational of these two built-in functions you can control the 
  3025. commented text inserted in the output code following the detection of a 
  3026. keyword. 
  3027.  
  3028.   You can replace all standard migration comments with a new set; you can 
  3029. suppress all comments and notes; you can add migration notes to the standard 
  3030. comments.  These options are all available with MiCL using SmNoComment and 
  3031. SmOutputNote. 
  3032.  
  3033. Navigation Links 
  3034.  
  3035.       CONTINUE - Global, Static and Local Variables 
  3036.       BACK - Migration Control 
  3037.       NOTES and TIPS 
  3038.       SECTION 2 - MiCL Programming 
  3039.       CONTENTS 
  3040.  
  3041.  
  3042. ΓòÉΓòÉΓòÉ 5.8.9. Global, Static and Local Variables ΓòÉΓòÉΓòÉ
  3043.  
  3044. Global, Static and Local Variables 
  3045.  
  3046.   Variables used in MiCL fall into three major categories: Process Global, 
  3047. Keyword Static and Local.  The life and scope of each category is quite 
  3048. different. 
  3049.  
  3050.   Process Global variables are designated with the leading characters "$G". 
  3051. Once a global variable is set, it is available to all keyword command sets 
  3052. throughout the process.  The value of a global variable can be changed at any 
  3053. time during the process run, by any keyword or event command set.  Furthermore, 
  3054. the global variables can be saved at any time during the process run through 
  3055. the execution of the built-in function "SmSaveVars".  The saved variables can 
  3056. be restored with their saved values using the function "SmLoadVars". 
  3057.  
  3058.   Keyword Static variables behave like global variables except that the scope 
  3059. of the Static variable is contained to the Keyword command set where it has 
  3060. been created.  The same static variable name can be used in multiple command 
  3061. sets, however the scope of each of these duplicate variable names is restricted 
  3062. to its own keyword. 
  3063.  
  3064.   The Keyword Static variable is ideal for maintaining keyword migration data 
  3065. and options throughout the process run.  As in the case of the global 
  3066. variables, the static variables can be saved to a hard file and restored when 
  3067. necessary. 
  3068.  
  3069.   Keyword Static variables are designated by the leading characters "$S". 
  3070.  
  3071.   The local variable's life only extends to the end of a command set.  The 
  3072. value of the variable is only available to the keyword command set where the 
  3073. variable is created and set.  Typically it is used for temporary or 
  3074. intermediate storage of keyword data, options and strings related to the 
  3075. individual encounter of a keyword during the migration process. 
  3076.  
  3077.   The predefined variables related to keyword context information are all local 
  3078. variables, created automatically during the migration process upon detection of 
  3079. a keyword encounter. 
  3080.  
  3081.   A local variable name can begin with any character A-Z, !, ? or _ .  Local 
  3082. variables used in template processing with the SmMigrateKeyword and 
  3083. SmOutputLine must begin with a "?" character. 
  3084.  
  3085.   All variable names processed in MiCL are case insensitive.  The names of 
  3086. control option buttons in the dialog functions are NOT variables but instead, 
  3087. are case sensitive literals. 
  3088.  
  3089. Related Topics 
  3090.  
  3091.       Preset Variables 
  3092.       Use of Templates 
  3093.       String and Variable Evaluation 
  3094.  
  3095.  Navigation Links 
  3096.  
  3097.       CONTINUE - String and Variable Evaluation 
  3098.       BACK - Migration Notes and Comments 
  3099.       NOTES and TIPS 
  3100.       SECTION 2 - MiCL Programming 
  3101.       CONTENTS 
  3102.  
  3103.  
  3104. ΓòÉΓòÉΓòÉ 5.8.10. String and Variable Evaluation ΓòÉΓòÉΓòÉ
  3105.  
  3106. String and Variable Evaluation 
  3107.  
  3108.   The evaluation of variables and strings fall into three categories: 
  3109. Templates, Arguments, and assignment expressions. 
  3110.  
  3111.   A Template is a string containing embedded variables.  When this string is 
  3112. evaluated, the variables are replaced by the string value of the variable while 
  3113. the rest of the evaluated string including all spacing and special characters 
  3114. remain unchanged. 
  3115.  
  3116.   Templates can be created within the command set and can be coded in the 
  3117. migration table using the ".Template" tag. 
  3118.  
  3119.   Template evaluation is performed on the argument of the following MiCL 
  3120. built-in functions: 
  3121.  
  3122.    SmMigrateKeyword (  Template )
  3123.    SmOutputLine ( Template )
  3124.    SmSendToEditor ( Template )
  3125.  
  3126.   Please note that the ONLY variables that are replaced by their string values 
  3127. are those beginning with "$" and "?".  Any other character string will be 
  3128. assumed to be part of the template and will be passed unchanged to the output 
  3129. of the evaluation. 
  3130.  
  3131.   Any Template enclosed in quotation marks will have the outer marks removed 
  3132. during the evaluation.  If the result is required to be contained in quotation 
  3133. then you must place the template string in double quotation. 
  3134.  
  3135.   The following are valid template strings: 
  3136.  
  3137.    $LFile($LLine)
  3138.    WinSetParent( $P1, ?Param2, TRUE);
  3139.    "'OS2.H'"
  3140.  
  3141.   An example of a template created within the command set may appear as: 
  3142.  
  3143.    $T1 = RETURN " = WinSetParent( $P1, $P2, TRUE):"
  3144.  
  3145.   Arguments to MiCL built-in functions other than those evaluated as templates 
  3146. (shown above) are evaluated as either the string value of a variable or a 
  3147. literal string in quotation. 
  3148.  
  3149.   The control option button IDs in the dialog functions SmListDlg, 
  3150. SmDisplayDlg, and SmPromptDlg are not evaluated but are used as entered. 
  3151.  
  3152.   Any argument variable that has not previously been created will be passed to 
  3153. the output without evaluation. 
  3154.  
  3155.   Evaluation of expressions in the assignment instruction combine literal 
  3156. strings and/or variable values.  The evaluation of the expression proceeds from 
  3157. left to right after the equal sign (designating an assignment instruction). 
  3158.  
  3159.   Spacing is maintained only within the literal strings, enclosed in quotation. 
  3160. All expression elements are concatenated. 
  3161.  
  3162.   The following is an example of expression evaluation. 
  3163.  
  3164.   $KEY contains "CreateWindow" 
  3165.  
  3166.   The command is shown below: 
  3167.  
  3168.    DISPLAY = "Unable to migrate: " $KEY ". Keyword is embedded."
  3169.    SmDisplayDlg( DISPLAY, OPTION, Ok | Abort )
  3170.  
  3171.   The resulting evaluation in the assignment instruction of DISPLAY is: 
  3172.  
  3173.    Unable to migrate the keyword: CreateWindow. Keyword is embedded.
  3174.  
  3175. Related Topics 
  3176.  
  3177.       Preset Variables 
  3178.       Use of Templates 
  3179.  
  3180.  Navigation Links 
  3181.  
  3182.       CONTINUE - Launching the Editor 
  3183.       BACK - Global, Static, and Local Variables 
  3184.       NOTES and TIPS 
  3185.       SECTION 2 - MiCL Programming 
  3186.       CONTENTS 
  3187.  
  3188.  
  3189. ΓòÉΓòÉΓòÉ 5.8.11. Launching the Editor ΓòÉΓòÉΓòÉ
  3190.  
  3191. Launching the Editor 
  3192.  
  3193.   The editor specified in the SMART setup options can be launched from the MiCL 
  3194. built-in function SmSendToEditor( ). The argument of this call is used as one 
  3195. of the arguments of a DosStartSession for the specified editor.  Additional 
  3196. arguments can be specified in the setup options for the editor and will be used 
  3197. each time this function is executed. 
  3198.  
  3199.   Typically the argument for this function is created as a template to contain 
  3200. the filename, line number, column number and an indicator to open the file as 
  3201. read only.  An example of this template argument is shown below: 
  3202.  
  3203.    $LFILE($LLINE:$LCOL)R
  3204.  
  3205.   Note that in this example the variables $LFile, $LLine, $LCol are all 
  3206. predefined variables that are automatically set before the execution of any 
  3207. line of code in a command set. 
  3208.  
  3209.   This template is specifically designed for The SMART Editor - The SMART 
  3210. Editor.  The SMART Editor will accept this parameter and open the specified 
  3211. file at the designated line number.  Furthermore the word at the specified 
  3212. column number will be highlighted.  A new instance of The SMART Editor will not 
  3213. be created by this call, if SLSTART is designated as the system editor. 
  3214. Instead The SMART Editor will immediately open the file at the point of the 
  3215. keyword encounter as specified by the template shown above. 
  3216.  
  3217.   As an additional feature, the use of the optional parameter "/F" in the setup 
  3218. options for SLSTART will force The SMART Editor to popup the specified file 
  3219. without having to select  "Open Waiting Files" (F10). 
  3220.  
  3221.   It is highly recommended that you create a project instance of The SMART 
  3222. Editor in the use of SMART.  Simply create a program object for The SMART 
  3223. Editor and place the project ID in the parameter of this instance with the 
  3224. /P:xxxx option.  "xxxx" should be the project ID for this special instance of 
  3225. The SMART Editor. "SMART" could be a good choice for this ID. 
  3226.  
  3227.   In a like fashion, identify this instance of The SMART Editor by placing a 
  3228. /P:xxxx parameter in the parameters field of the SMART editor specification in 
  3229. the Setup Options dialog. 
  3230.  
  3231.   If you are not using The SMART Editor as your designated SMART editor, the 
  3232. results using SmSendToEditor will depend upon the capabilities of the specified 
  3233. editor. 
  3234.  
  3235.   It is important that you halt the migration process after executing this 
  3236. instruction.  This will allow your editor to display the source code in an 
  3237. orderly fashion.  Executing any one of the dialog functions ( SmListDlg, 
  3238. SmDisplayDlg, and SmPromptDlg ) will temporarily halt the process until the 
  3239. user responds to the dialog.  Failure to halt the migration process after 
  3240. executing SmSendToEditor may cause a general OS/2 system failure. 
  3241.  
  3242. Related Topics 
  3243.  
  3244.       Use of Dialog Functions 
  3245.  
  3246.  Navigation Links 
  3247.  
  3248.       CONTINUE - Testing MiCL 
  3249.       BACK - String and Variable Evaluation 
  3250.       NOTES and TIPS 
  3251.       SECTION 2 - MiCL Programming 
  3252.       CONTENTS 
  3253.  
  3254.  
  3255. ΓòÉΓòÉΓòÉ 5.8.12. Testing MiCL Command Sets ΓòÉΓòÉΓòÉ
  3256.  
  3257. Testing MiCL Command Sets 
  3258.  
  3259.   You are advised to perform thorough testing of any MiCL programs that you 
  3260. create.  MiCL processing does not perform extensive detection and reporting of 
  3261. programming bugs.  Unexpected results may occur from programming errors. 
  3262.  
  3263.   This version of SMART includes a trace facility for MiCL. 
  3264.  
  3265.   To activate MiCL Trace select "Trace MiCL" under the "Migration" main menu 
  3266. item. A display will appear.  You can size and move the trace display. 
  3267.  
  3268.   Next enter the keyword to trace and press 'Trace Keyword' or press "Trace 
  3269. ALL" to trace all keywords executing MiCL Commands. 
  3270.  
  3271.   Once the trace begins, press <Enter> to step through each command line. 
  3272.  
  3273.   At the conclusion of tracing through a keyword command set, you may cancel 
  3274. the trace, advance to the next keyword encounter, change the name of the 
  3275. keyword to trace, or terminate the migration process. (Press <Enter> or select 
  3276. the appropriate item under the "Trace" menu on the MiCL Trace Window.) 
  3277.  
  3278.   Closing the Trace Facility will cancel the trace and the migration process 
  3279. will proceed naturally through the process. 
  3280.  
  3281.   The best way to test your MiCL programs to create a UDMD containing the MiCL 
  3282. commands as they will appear in the migration table.  Then, prepare a sample 
  3283. source code file containing various different examples demonstrating the use of 
  3284. the programmed keyword. 
  3285.  
  3286.   You can quickly create a UDMD from the MiCL commands, and process the test 
  3287. source code with the SMART Migration.  Be sure to select the newly created UDMD 
  3288. table as the override migration table. 
  3289.  
  3290.   Once you are satisfied with the test results from this small test file, you 
  3291. may wish to process a selected set of files from your actual source code. 
  3292. After you have processed this migration test, carefully review the resulting 
  3293. output to insure that the migration was performed as programmed. 
  3294.  
  3295. Navigation Links 
  3296.  
  3297.       CONTINUE - Reference 
  3298.       BACK - String and Variable Evaluation 
  3299.       NOTES and TIPS 
  3300.       SECTION 2 - MiCL Programming 
  3301.       CONTENTS 
  3302.  
  3303.  
  3304. ΓòÉΓòÉΓòÉ 6. Reference ΓòÉΓòÉΓòÉ
  3305.  
  3306. Reference 
  3307.  
  3308.         Reserved Words 
  3309.         Keyword Identifier Codes 
  3310.  
  3311.  Navigation Links 
  3312.  
  3313.       CONTINUE - Reserved Words 
  3314.       BACK - Testing MiCL 
  3315.       CONTENTS 
  3316.  
  3317.  
  3318. ΓòÉΓòÉΓòÉ 6.1. Reserved Words ΓòÉΓòÉΓòÉ
  3319.  
  3320. Reserved Words 
  3321.  
  3322.   The following words are reserved by the SMART Migration Command Language 
  3323. Processor and should not be used as a variable name in your commands.  The 
  3324. definition and purpose of these reserved words are found elsewhere in this 
  3325. document. 
  3326.  
  3327.   Remember, all command language text not enclosed in quotes is treated as 
  3328. uppercase. Also, user variables cannot start with a dollar sign ($) this is 
  3329. reserved for SMART predefined variables (however $G and $S variables can be 
  3330. custom user identified with up to eight characters). 
  3331.  
  3332.        ALL 
  3333.        AND 
  3334.        BLOCK 
  3335.        DEFAULT 
  3336.        DO 
  3337.        ELSE 
  3338.        END 
  3339.        EXIT 
  3340.        GLOBAL 
  3341.        IF 
  3342.        KEYWORD 
  3343.        LCOMMENT 
  3344.        LINE 
  3345.        NOT 
  3346.        PROTOTYPE 
  3347.        OR 
  3348.        SAMPLE 
  3349.        SCOMMENT 
  3350.        SmDisplayDlg 
  3351.        SmGetListName 
  3352.        SmGetListPath 
  3353.        SmGetSmartPath 
  3354.        SmIgnoreKeyword 
  3355.        SmLoadVars 
  3356.        SmMigrateKeyword 
  3357.        SmNoComment 
  3358.        SmNoMigrate 
  3359.        SmOutputLine 
  3360.        SmOutputNote 
  3361.        SmPromptDlg 
  3362.        SmRemove 
  3363.        SmSaveVars 
  3364.        SmSendToEditor 
  3365.        STATIC 
  3366.        TEMPLATE 
  3367.        TERMINATE 
  3368.        THEN 
  3369.  
  3370.  Navigation Links 
  3371.  
  3372.       CONTINUE - Keyword Identifier Codes 
  3373.       BACK - Reference 
  3374.       REFERENCE 
  3375.       CONTENTS 
  3376.  
  3377.  
  3378. ΓòÉΓòÉΓòÉ 6.2. Keyword Identifier Codes ΓòÉΓòÉΓòÉ
  3379.  
  3380. Keyword Identifier Codes 
  3381.  
  3382. Keyword Category 
  3383.  
  3384.  000            Informational only 
  3385.  010            Literal replacement 
  3386.  020            Replacement with parameter changes 
  3387.  030            Change with more / less API calls 
  3388.  040            Logic changes required 
  3389.  050            Functionality does not exist 
  3390.  999            Dictionary entry not defined 
  3391.  
  3392.  Keyword Type 
  3393.  
  3394.  010            Function 
  3395.  020            Message 
  3396.  030            Symbol 
  3397.  040            typedef 
  3398.  999            Unknown 
  3399.  
  3400.  Functional Area - Windows 
  3401.  
  3402.  010            Module-Management 
  3403.  020            Segment 
  3404.  030            Memory-Management 
  3405.  040            Operating-System Interrupt 
  3406.  050            Task 
  3407.  060            Resource-Management 
  3408.  070            String-Manipulation 
  3409.  080            Atom-Management 
  3410.  090            Initialization-File 
  3411.  100            Communication 
  3412.  110            Sound 
  3413.  120            Utility Macros and Functions 
  3414.  130            File I/O 
  3415.  140            Debugging 
  3416.  150            Optimization-Tool 
  3417.  160            Application-Execution 
  3418.  200            Message 
  3419.  210            Window-Creation 
  3420.  215            Multiple-Document Interface 
  3421.  220            Display and Movement 
  3422.  230            Input 
  3423.  240            Hardware 
  3424.  250            Painting 
  3425.  260            Dialogs 
  3426.  270            Scrolling 
  3427.  280            Menu 
  3428.  290            Information 
  3429.  300            System 
  3430.  310            Clipboard 
  3431.  320            Error 
  3432.  330            Caret 
  3433.  340            Cursor 
  3434.  345            Icon 
  3435.  350            Hook 
  3436.  360            Property 
  3437.  370            Rectangle 
  3438.  400            Device-Context 
  3439.  410            Drawing-Tool 
  3440.  420            Color-Palette 
  3441.  430            Drawing-Attribute 
  3442.  440            Mapping 
  3443.  450            Coordinate 
  3444.  460            Region 
  3445.  470            Clipping 
  3446.  480            Line-Output 
  3447.  490            Ellipse and Polygon 
  3448.  500            Bitmap 
  3449.  510            Device-Independent Bitmap 
  3450.  520            Text 
  3451.  530            Font 
  3452.  540            Metafile 
  3453.  550            Device-Control 
  3454.  560            Printer 
  3455.  570            Environment 
  3456.  580            Network 
  3457.  800            WinMem32 
  3458.  810            Windows Macros 
  3459.  820            File Manager Extensions 
  3460.  830            Version Control Extensions 
  3461.  840            ToolHelp Extensions 
  3462.  850            Stress Extensions 
  3463.  860            Shell Extensions 
  3464.  865            Screen Saver Extensions 
  3465.  870            Print Spooling Extensions 
  3466.  875            Pen Windows Extensions 
  3467.  880            OLE 
  3468.  890            MultiMedia Extensions 
  3469.  891            MMP Extensions 
  3470.  892            DispDib Extensions 
  3471.  895            File Compression Extensions 
  3472.  900            Device Driver extensions 
  3473.  905            Dialog Extensions 
  3474.  910            DDEML 
  3475.  911            DDE 
  3476.  915            Dialog Editor Extensions 
  3477.  920            Control Panel Extensions 
  3478.  925            Common Dialogs 
  3479.  926            Color Dialog 
  3480.  930            Common Dialog Errors 
  3481.  940            Typedefines 
  3482.  990            Miscellaneous 
  3483.  999            Functional Area not defined 
  3484.  
  3485.  Functional Area - OS/2 
  3486.  
  3487.  010            Module-Management 
  3488.  020            Segment 
  3489.  030            Memory-Management 
  3490.  040            Semaphores 
  3491.  050            Tasks and Threads 
  3492.  060            Resource-Management 
  3493.  070            String-Manipulation 
  3494.  080            Atom-Management 
  3495.  090            Profile-Management 
  3496.  100            Pipes and Queues 
  3497.  110            Sound 
  3498.  120            Utility Macros and Functions 
  3499.  130            File I/O 
  3500.  140            Device Drivers 
  3501.  150            Printing 
  3502.  160            Application-Execution 
  3503.  170            Signals and Monitors 
  3504.  180            Keyboard Interface (Kbd) 
  3505.  190            VIO Interface (Vio) 
  3506.  200            Mouse Inteface (Mou) 
  3507.  210            Window Creation 
  3508.  220            Display and Movement 
  3509.  230            Input 
  3510.  250            Painting 
  3511.  260            Dialog 
  3512.  270            Scrolling 
  3513.  280            Menu 
  3514.  290            Information 
  3515.  310            Clipboard 
  3516.  320            Message 
  3517.  330            Cursor 
  3518.  340            Pointer 
  3519.  350            Hook 
  3520.  370            Rectangle 
  3521.  420            Color-Palette 
  3522.  450            Coordinate 
  3523.  460            Region 
  3524.  480            Line-Output 
  3525.  500            Bitmap 
  3526.  520            Text 
  3527.  530            Font 
  3528.  590            Graphics-Engine 
  3529.  600            Drag-Drop 
  3530.  910            DDE 
  3531.  920            Switch-List 
  3532.  930            Spool-Manager 
  3533.  940            Direct-Device File System 
  3534.  950            Print-Spooling 
  3535.  990            Miscellaneous 
  3536.  999            Functional Area 
  3537.  
  3538.  
  3539.       BACK - Reserved Words 
  3540.       REFERENCE 
  3541.       CONTENTS 
  3542.