home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 10 Tools / 10-Tools.zip / zfamily.zip / zfamily / ZCVFUNCS / HELP / ZCVFUNCS.INF (.txt) next >
OS/2 Help File  |  1993-11-19  |  58KB  |  1,563 lines
  1.  
  2. ΓòÉΓòÉΓòÉ 1. Document Content ΓòÉΓòÉΓòÉ
  3.  
  4. This document is made up of five parts: 
  5.  
  6. Library Card 
  7.    General information card for this library. 
  8.  
  9. Installation Guide 
  10.    How to install the Z Family/2 reusable library and how to use the installed 
  11.    files. 
  12.  
  13. User's Guide 
  14.    How to integrate the library with your application and how to call the 
  15.    corresponding functions and macros. 
  16.  
  17. Reference Manual 
  18.    Reference information for the functions, macros and structures provided by 
  19.    this library. 
  20.  
  21. Sample Program 
  22.    How to call and use the sample program. 
  23.  
  24.  
  25. ΓòÉΓòÉΓòÉ 2. Library card ΓòÉΓòÉΓòÉ
  26.  
  27.  
  28. ΓòÉΓòÉΓòÉ <hidden> Dummy ΓòÉΓòÉΓòÉ
  29.  
  30. Package:      ZCVFUNCS 
  31.  
  32. Library:      FMZCVFUN.DLL 
  33.  
  34. Version:      2.20 
  35.  
  36. Requirements: 
  37.  
  38.   OS/2 2.x, C Set/2 or IBM C/C++ Tools 2.0, Toolkit 2.x, ACSSVC.DLL (an APPC 
  39.   Dynamic Link Library). 
  40.  
  41. Trademarks 
  42.  
  43.  
  44. ΓòÉΓòÉΓòÉ <hidden> Dummy ΓòÉΓòÉΓòÉ
  45.  
  46.  
  47. ΓòÉΓòÉΓòÉ <hidden> Dummy ΓòÉΓòÉΓòÉ
  48.  
  49. Contact:      Dr. Dario de Judicibus 
  50. IBMMAIL:      ITIBM98W 
  51. Internet:     ddj@vnet.ibm.com 
  52.  
  53.  
  54. ΓòÉΓòÉΓòÉ 3. Installation Guide ΓòÉΓòÉΓòÉ
  55.  
  56. Select one: 
  57.  
  58. Library installation 
  59.  
  60. The expanded tree 
  61.  
  62.  
  63. ΓòÉΓòÉΓòÉ 3.1. Library installation ΓòÉΓòÉΓòÉ
  64.  
  65. Select one: 
  66.  
  67. Γûá Package content
  68. Γûá How to install the library
  69.  
  70.  
  71. ΓòÉΓòÉΓòÉ 3.1.1. Package content ΓòÉΓòÉΓòÉ
  72.  
  73. FMZCVFUN.DLL is distributed as a package containing the following files: 
  74.  
  75.    ZCVFUNCS.ZIP            A compressed file which contains the library 
  76.                            modules. 
  77.    ZCVFUNCS.INF            The on-line documentation for this reusable library. 
  78.  
  79.  
  80. ΓòÉΓòÉΓòÉ 3.1.2. How to install the library ΓòÉΓòÉΓòÉ
  81.  
  82. To install the libraries, you have to perform the following steps: 
  83.  
  84.   1. Locate the directory of the CD-ROM, remote partition, or diskette where 
  85.      ZCVFUNCS.ZIP is placed. Let's say, for example, P:\ZFAMILY. 
  86.  
  87.   2. Move to the directory on your system where you want to install the 
  88.      reusable library. For example, move to D:\REUSE. 
  89.  
  90.   3. Unpack the ZIP file by using option -d. Note that the option must be lower 
  91.      case. In our case, issue the following command: 
  92.  
  93.            [D:\REUSE]  PKUNZIP2 -d P:\ZFAMILY\ZCVFUNCS.ZIP
  94.  
  95.   4. When the command finishes, a new directory is available on your system. In 
  96.      our example, P:\ZFAMILY\ZCV. This directory contains several 
  97.      sub-directories which contains all the files needed to use the reusable 
  98.      library. The directory tree is described in Library Tree. The content of 
  99.      each sub-directory is described in detail in Content of directories. 
  100.  
  101.   5. To use the library, you must now move the unpacked files to the 
  102.      appropriate directories in your development environment. In particular 
  103.      move 
  104.  
  105.     o the headers from .\ZCV\H to any directory listed in your INCLUDE 
  106.       environment variable. 
  107.  
  108.     o the import and/or object libraries from .\ZCV\LIB and .\ZCV\DEVEL to any 
  109.       directory listed in your LIB environment variable. 
  110.  
  111.     o the dynamic link libraries from .\ZCV\DLL to any directory listed in your 
  112.       LIBPATH environment variable. 
  113.  
  114.      You may also want to move this file from .\ZCV\HELP to any directory 
  115.      listed in your BOOKSHELF environment variable. 
  116.  
  117.  Now you are ready to work with the ZCV reusable library. 
  118.  
  119.  
  120. ΓòÉΓòÉΓòÉ 3.2. The expanded tree ΓòÉΓòÉΓòÉ
  121.  
  122. Select one: 
  123.  
  124. Γûá Library tree
  125. Γûá Content of directories
  126.  
  127.  
  128. ΓòÉΓòÉΓòÉ 3.2.1. Library tree ΓòÉΓòÉΓòÉ
  129.  
  130. When you unpack ZCVFUNCS.ZIP, a new sub-directory is created on your system: 
  131. ZCV. It has the following structure: 
  132.  
  133.   current dir
  134.   Γöé
  135.   Γöé ZCV
  136.   Γö£ΓöÇΓöÉ
  137.   Γöé Γö£ΓöÇΓöÇΓöÇΓöÇ H
  138.   . Γö£ΓöÇΓöÇΓöÇΓöÇ DLL
  139.   . Γö£ΓöÇΓöÇΓöÇΓöÇ LIB
  140.   . Γö£ΓöÇΓöÇΓöÇΓöÇ MRI
  141.   . Γö£ΓöÇΓöÇΓöÇΓöÇ HELP
  142.   . Γö£ΓöÇΓöÇΓöÇΓöÇ DEVEL
  143.   . ΓööΓöÇΓöÇΓöÇΓöÇ SAMPLE
  144.  
  145.  
  146. ΓòÉΓòÉΓòÉ 3.2.2. Content of directories ΓòÉΓòÉΓòÉ
  147.  
  148. Here is the list of the directories that are created when ZCVFUNCS.ZIP is 
  149. unpacked as described in How to install the library.  The content of each 
  150. directory is described in detail. 
  151.  
  152. The H sub-directory contains all the header files (H  and RCH) to be added to 
  153. the INCLUDE path of the application development environment. Move all the files 
  154. from this directory to the appropriate path in your environment. 
  155.  
  156.    Important If you use other Z Family/2 reusable libraries in your development 
  157.    environment, ensure that you are using the latest version of the zgeneral.h 
  158.    header file, which is available in all  the library packages. You may do 
  159.    that by comparing the update dates in the prologue of the header file. 
  160.  
  161.        /*
  162.        **  Module  : ZGENERAL.H
  163.        **  Authors : Dario de Judicibus (DEJUDICI at ROMEPPC)
  164.        **       Alessandro Cavallini (CAVALLI at ROMEPPC)
  165.        **       Giacomo Lenoci
  166.        **  Created : 10 Jan 1992
  167.        **  Updated : 01 Feb 1993
  168.        **  Version : 2.30
  169.        **  Content : General includes for all Z Family/2 DLLs
  170.        **  Product : Z Family/2 Project (5641-504) FMZ
  171.        **
  172.        */
  173.  
  174.  The DLL sub-directory contains all the dynamic link library or libraries (DLL) 
  175.  to be added to the LIBPATH path of the application development environment and 
  176.  of the run environment. Move all the files from this directory to the 
  177.  appropriate path in your environment. 
  178.  
  179.  The LIB sub-directory contains all the import library or libraries (LIB) to be 
  180.  added to the LIB path of the application development environment. Move all the 
  181.  files from this directory to the appropriate path in your environment. 
  182.  
  183.  The MRI sub-directory contains all the text that might be translated to other 
  184.  languages (see Machine Readable Information for additional information). 
  185.  
  186.  The HELP sub-directory contains the library documentation and a news file 
  187.  (ZCVNEWS.DOC) containing modifications applied at the last minute and not 
  188.  available in the on-line manuals, along with the history of changes. 
  189.  
  190.  The DEVEL sub-directory contains the object library or libraries (LIB) and the 
  191.  sample DEF and MAK files that can be used to generate your own DLL(s) (see 
  192.  Create your own library for details). 
  193.  
  194.  The SAMPLE sub-directory contains the source code and the executable code of 
  195.  the sample program. It doesn't contain the DLL file(s) so to run the sample, 
  196.  you must ensure that all the required DLL files have been copied to a 
  197.  directory in your LIBPATH. The DLL files for this library as well as those 
  198.  belonging on any pre-requisite Z Family/2 Reusable Library need to be in a 
  199.  directory in your LIBPATH. 
  200.  
  201.    Important If the library depends on other Z Family/2 reusable libraries, all 
  202.    the files belonging to the pre-requisite libraries will be part of the 
  203.    dependent library only in the beta versions of the package. 
  204.  
  205.    The final version won't contain any pre-requisite file.  That is true for 
  206.    the SAMPLE sub-directory too. So, you won't be able to recompile the sample 
  207.    program unless you install the pre-requisite packages too. 
  208.  
  209.  
  210. ΓòÉΓòÉΓòÉ 4. User's Guide ΓòÉΓòÉΓòÉ
  211.  
  212. Select one: 
  213.  
  214.  General information 
  215.  
  216.  Basic topics 
  217.  
  218.  Advanced topics 
  219.  
  220.  
  221. ΓòÉΓòÉΓòÉ 4.1. General information ΓòÉΓòÉΓòÉ
  222.  
  223. Select one: 
  224.  
  225. Γûá Library overview
  226. Γûá Include files
  227. Γûá Requirements
  228. Γûá Development rules
  229. Γûá Trademarks
  230.  
  231.  
  232. ΓòÉΓòÉΓòÉ 4.1.1. Library overview ΓòÉΓòÉΓòÉ
  233.  
  234. This library contains a set of functions to convert texts from a single-byte 
  235. coded character set to another. These function allow the programmer to 
  236.  
  237.  o create translation tables 
  238.  
  239.  o convert character streams and null-terminated strings 
  240.  
  241.  o convert text files 
  242.  
  243.  FMZCVFUN.DLL is not yet DBCS enabled. 
  244.  
  245.  Several coded character sets (CCSIDs) are supported. For details refer to 
  246.  Supported CCSIDs. 
  247.  
  248.  
  249. ΓòÉΓòÉΓòÉ 4.1.2. Include files ΓòÉΓòÉΓòÉ
  250.  
  251. The system include files that are required to use this library are: 
  252.  
  253.  #define INCL_PM
  254.  #define INCL_DOS
  255.  #define INCL_DOSNLS
  256.  #include <os2.h>
  257.  #include <stdio.h>
  258.  #include <stdlib.h>
  259.  #include <stdarg.h>
  260.  #include <signal.h>
  261.  #include <string.h>
  262.  #include <ctype.h>
  263.  
  264. The specific include files that are required to use this library are: 
  265.  
  266.  zgeneral.h 
  267.       Definitions and types for all Z Family/2 Reusable Libraries. 
  268.  
  269.  zcvdefs.h 
  270.       Macro and constants for this library. 
  271.  
  272.  zcvtypes.h 
  273.       Type definitions for this library. 
  274.  
  275.  zcvproto.h 
  276.       Function prototypes for this library. 
  277.  
  278.  Note:  The specific includes must be included in the order as listed above. 
  279.  
  280.  
  281. ΓòÉΓòÉΓòÉ 4.1.3. Requirements ΓòÉΓòÉΓòÉ
  282.  
  283. FMZCVFUN.DLL is intended to run under OS/2 2.x.  It doesn't run under previous 
  284. versions of OS/2. 
  285.  
  286. FMZCVFUN.DLL has been compiled by IBM C/C++ Tools 2.0 and statically linked to 
  287. the C run-time libraries. Then you don't need the run-time libraries to use it. 
  288.  
  289. This library needs the APPC Dynamic Link Libraries provided with the 
  290. Communications Manager/2. 
  291.  
  292. In particular ACSSVC.DLL must be available. 
  293.  
  294. Notes 
  295.  
  296. FMZCVFUN.DLL functions can be called either from C or from C++. In addition, an 
  297. exception handler is registered for each exported function. 
  298.  
  299. A sample program that shows how to use FMZCVFUN.DLL functions is also provided 
  300. in the DLL's package. A short description of that sample is available in Sample 
  301. program tutorial. 
  302.  
  303. The sample program uses the IMPORTS statement in its .DEF to import the 
  304. FMZCVFUN.DLL functions. File FMZCVFUN.LIB is also provided as an alternative 
  305. solution. 
  306.  
  307. It is also possible to create a clone of FMZCVFUN.DLL by using the files 
  308. available in the DEVEL sub-directory of the tree created by exploding the ZIP 
  309. file distributed with the package (see Create your own library). 
  310.  
  311.  
  312. ΓòÉΓòÉΓòÉ 4.1.4. Development rules ΓòÉΓòÉΓòÉ
  313.  
  314. To safely integrate any Z Family/2 Reusable Library in your application, you 
  315. need to follow a simple set of rules: 
  316.  
  317.   1. Do not use names beginning by a lower case "z" for 
  318.  
  319.     o functions 
  320.     o macros 
  321.     o global structures 
  322.     o types 
  323.     o constants 
  324.     o #define 
  325.     o global variables 
  326.  
  327.   2. Do not use names beginning by a "z" for 
  328.  
  329.     o include files (.H) 
  330.     o dynamic link libraries (.DLL) 
  331.  
  332.  Follow these rules and your code can take full advantage of the services 
  333.  provided by the current and future Z Family/2 Reusable Libraries. 
  334.  
  335.  
  336. ΓòÉΓòÉΓòÉ 4.1.5. Trademarks ΓòÉΓòÉΓòÉ
  337.  
  338. IBM Z Family/2 Reusable Libraries is copyrighted by IBM Corporation. 
  339.  
  340. IBM Corporation trademarks 
  341.  
  342.  APPC
  343.  CUA
  344.  Common User Access
  345.  Communications Manager/2
  346.  IBM
  347.  IBM C Set/2
  348.  IBM C/C++ Tools
  349.  Operating System/2
  350.  OS/2
  351.  Presentation Manager
  352.  SAA
  353.  Systems Application Architecture
  354.  Workplace Shell
  355.  
  356. Other trademarks 
  357.  
  358.  Intel is a trademark of the Intel Corporation.
  359.  Microsoft and Windows are trademarks of the Microsoft Corporation.
  360.  PKZIP and PKUNZIP are trademarks of the PKWare Corporation.
  361.  80386 is a trademark of the Intel Corporation.
  362.  
  363.  
  364. ΓòÉΓòÉΓòÉ 4.2. Basic topics ΓòÉΓòÉΓòÉ
  365.  
  366. Select one: 
  367.  
  368. Γûá Tables and streams
  369. Γûá Supported CCSIDs
  370.  
  371.  
  372. ΓòÉΓòÉΓòÉ 4.2.1. Tables and streams ΓòÉΓòÉΓòÉ
  373.  
  374. Select one: 
  375.  
  376. Γûá Tables
  377. Γûá Streams
  378.  
  379.  
  380. ΓòÉΓòÉΓòÉ 4.2.1.1. Tables ΓòÉΓòÉΓòÉ
  381.  
  382. A translation table is a memory area of 256 bytes, which contains the values to 
  383. be used to translate a text from a single-byte coded character set to another. 
  384.  
  385. There are two kinds of translation tables: generated and user-provided. 
  386.  
  387. A generated translation table is created by zcvMakeTable() providing the source 
  388. and target CCSIDs (Coded Character Set Identifiers). 
  389.  
  390. A user-provided translation table is any array of 256 characters where each 
  391. element is different from the others. That is a translation table must be a 
  392. biunivocal operator. 
  393.  
  394. Since zcvMakeTable() takes advantage of an APPC service to generate the table, 
  395. and since such a service requires a 16:16 pointer rather than a 0:32 one, it is 
  396. necessary to allocate the table in a certain way. To avoid to bother the 
  397. developer with such details, specific allocation and freeing services are 
  398. provided: zcvAllocTable() and zcvFreeTable(). 
  399.  
  400. Such functions are requested for generated translation table, and highly 
  401. recommended for user-provided table too. In the latter case, the developer may 
  402. copy the existent table to the allocated area by 
  403.  
  404.  (void)memcpy( (char *)trans_table, user_table, 256 ) ;
  405.  
  406.  
  407. ΓòÉΓòÉΓòÉ 4.2.1.2. Streams ΓòÉΓòÉΓòÉ
  408.  
  409. A character stream is a sequence of characters in 0x00 to 0xFF range, NULL 
  410. included. 
  411.  
  412. On the other side, a null terminated string is a character stream in 0x01 to 
  413. 0xFF range, where the NULL is used to terminate the sequence and is not 
  414. considered as part of the string. 
  415.  
  416. zcvConvertCharStream() allows to convert either character streams and null 
  417. terminated strings according to a provided translation table. 
  418.  
  419.  
  420. ΓòÉΓòÉΓòÉ 4.2.2. Supported CCSIDs ΓòÉΓòÉΓòÉ
  421.  
  422. The coded character sets supported by the function that generates the 
  423. translation tables, that is zcvMakeTable(), could be obtained by calling 
  424. zcvSupportedCCSIDs(). In theory they might be different from a country to 
  425. another, depending on the installation options for each single machine. At the 
  426. moment, anyway, they are the same for all SBCS systems. 
  427.  
  428. Since there is currently no way to extract the list of CCSIDs supported by 
  429. ASCSVC.DLL by using the APPC services, I had to hardcode it in a static 
  430. constant array included in FMZCVFUN.DLL. 
  431.  
  432. The only way I know to obtain that list, is to generate a set of ┬╖CPT files 
  433. (codepage tables) by moving to your \CMLIB directory, and launching 
  434. ACSGCCRT.EXE.  You'll obtain a list of files which correspond to the CCSID's 
  435. that are supported on your machine. 
  436.  
  437. I decided do not use such a system to get dynamically the CCSIDs' list, to 
  438. avoid to create unwanted files in your CMLIB directory. 
  439.  
  440. Hereinafter is the list that I obtained on my PS/2, just for reference: 
  441.  
  442. PC CCSIDs 
  443.  
  444. 437   : US and others         850   : Multilingual
  445. 852   : ROECE Latin-2 Multilingual   857   : Turkey Latin 5
  446. 862   : Hebrew (migration)       864   : Arabic
  447. 860   : Portuguese           861   : Iceland
  448. 863   : Canadian-French        865   : Denmark/Norway
  449. 1011   : ISO-7 Germany         1010   : ISO-7 French
  450. 1012   : ISO-7 Italy
  451.  
  452. Host CCSIDs 
  453.  
  454. 037   : US and others         273   : Germany
  455. 277   : Denmark/Norway         278   : Finland/Sweden
  456. 280   : Italy             284   : Spain/Latin America
  457. 285   : UK               297   : France
  458. 500   : Belgium/Multilingual      871   : Iceland
  459. 310   : APL 2             367   : ?
  460.  
  461. Other CCSIDs 
  462.  
  463. 65072  : ?               65076  : ?
  464. 65077  : ?               64437  : ?
  465. 64850  : ?               64860  : ?
  466. 64861  : ?               64863  : ?
  467. 64865  : ?               65000  : ?
  468. 65001  : ?               65002  : ?
  469. 65003  : ?               65004  : ?
  470. 65005  : ?               65006  : ?
  471. 65100  : ?
  472.  
  473.  
  474. ΓòÉΓòÉΓòÉ 4.3. Advanced topics ΓòÉΓòÉΓòÉ
  475.  
  476. Select one: 
  477.  
  478. Γûá Machine Readable Information
  479. Γûá Signal handling
  480. Γûá Create your own library
  481. Γûá How to generate the clone
  482. Γûá How to use the object library
  483.  
  484.  
  485. ΓòÉΓòÉΓòÉ 4.3.1. Machine Readable Information ΓòÉΓòÉΓòÉ
  486.  
  487. If the library contains translatable pieces of information, they are contained 
  488. in resource files available in the MRI sub-directory of the ZCV directory, 
  489. created at installation time (see Installation). 
  490.  
  491. To use these resource files, move all the header files in the H sub-directory 
  492. to the appropriate path in your development environment, translate the resource 
  493. files to the target language, recompile the file by using the command 
  494.  
  495.  rc -r <resource>.RC
  496.  
  497. to generate the corresponding RES file, and apply the result to the DLL file by 
  498. using the command 
  499.  
  500.  rc <resource>.RES <name>.DLL
  501.  
  502. Note that <name> is not FMZCVFUN but the name of the DLL cloned as described in 
  503. Create your own library. 
  504.  
  505.  
  506. ΓòÉΓòÉΓòÉ 4.3.2. Signal handling ΓòÉΓòÉΓòÉ
  507.  
  508. FMZCVFUN.DLL enables the handling of signals as follows. 
  509.  
  510. First, each exported function is preceeded in code by the corresponding pragma 
  511. handler: 
  512.  
  513.    Sample 
  514.  
  515.        #pragma handler(zcvLibraryVersion)
  516.  
  517.        VOID EXPENTRY zcvLibraryVersion
  518.         .
  519.         .
  520.         .
  521.  
  522.  Second, a standard function, available in any Z Family/2 reusable library, is 
  523.  provided to register a user's signal handler: zcvRegisterSignal (see 
  524.  zcvRegisterSignal). 
  525.  
  526.  The user's signal handler is a function that accepts as input parameter an 
  527.  integer, and returns a void. Here is a sample signal handler: 
  528.  
  529.    Sample 
  530.  
  531.        void UserSignalHandler (int signal)
  532.        {
  533.         switch (signal)
  534.         {
  535.          case SIGILL  : /* Prepare to handle SIGILL  */ break ;
  536.          case SIGSEGV : /* Prepare to handle SIGSEGV  */ break ;
  537.          case SIGFPE  : /* Prepare to handle SIGFPE  */ break ;
  538.          case SIGTERM : /* Prepare to handle SIGTERM  */ break ;
  539.          case SIGABRT : /* Prepare to handle SIGABRT  */ break ;
  540.          case SIGINT  : /* Prepare to handle SIGINT  */ break ;
  541.          case SIGUSR1 : /* Prepare to handle SIGUSR1  */ break ;
  542.          case SIGUSR2 : /* Prepare to handle SIGUSR2  */ break ;
  543.          case SIGUSR3 : /* Prepare to handle SIGUSR3  */ break ;
  544.          case SIGBREAK: /* Prepare to handle SIGBREAK */ break ;
  545.          default    : /* Unknown signal       */ break ;
  546.         }
  547.  
  548.         /*
  549.         **  Handle the received signal according to the previous
  550.         **  preparation. In general, show a message and terminate
  551.         **  the program.
  552.         */
  553.  
  554.        }
  555.  
  556.  
  557. ΓòÉΓòÉΓòÉ 4.3.3. Create your own library ΓòÉΓòÉΓòÉ
  558.  
  559. It is possible for the reuser to decide to clone a Z Family/2 reusable library 
  560. with a different name.  Since the source code is not available to reusers, it 
  561. is possible to do that by using the files in the DEVEL sub-directory. 
  562.  
  563.    Important These files are not intended to be used as they are, but should be 
  564.    modified as described below. 
  565.  
  566.  The DEVEL directory contains at least  four files: 
  567.  
  568.  ZCVFUNCS.LIB        An object library 
  569.  ZCVFUNCS.DEF        A skeleton for the definition file 
  570.  ZCVCLONE.MAK        A skeleton for the make file 
  571.  ZCVSTUB.C           A stub file used to generate the library 
  572.  
  573.  In addition, it may also contain one or more resource files, that is 
  574.  ZCVxxxxx.RES files. 
  575.  
  576.    Important 
  577.  
  578.    This library may need to load resources from itself, or to get its module 
  579.    handle. If you clone the library and change its name, it has no way to 
  580.    automatically know which is its new name. So you need to tell it about. You 
  581.    can do that by using the zcvSetLibraryName() function. 
  582.  
  583.  
  584. ΓòÉΓòÉΓòÉ 4.3.4. Create your own library ΓòÉΓòÉΓòÉ
  585.  
  586. To generate a clone of FMZCVFUN.DLL with a different name, you have to execute 
  587. the following steps: 
  588.  
  589.   1. Edit ZCVCLONE.MAK (see Skeleton of a makefile to clone a Z Family/2 DLL) 
  590.      changing USRNAME to the desired name. Let's say, for example, DLLCLONE. 
  591.      You may add other instructions to this make file, but be careful if you 
  592.      change the existing ones.  In particular, the OPTIONS constant contains 
  593.      the same options used to compile FMZCVFUN.DLL. If you change them, the new 
  594.      DLL may not work as expected. 
  595.  
  596.      Skeleton of a makefile to clone a Z Family/2 DLL 
  597.  
  598.           #
  599.           #  Module   : ZxxCLONE.MAK
  600.           #  Authors  : Luca Miccoli (MICCOLI at ROMEPPC)
  601.           #  Reviewer  : Dario de Judicibus (DEJUDICI at ROMEPPC)
  602.           #  Created  : 06 Apr 1993
  603.           #  Reviewed  : 21 Apr 1993
  604.           #  Version  : 1.00
  605.           #  Content  : Make File for Z Family/2 Clones
  606.           #
  607.           #  ------------------------------------------------------------------------------
  608.           #
  609.           #  NOTE : This is a SAMPLE makefile. You may need to modify it to satisfy your
  610.           #     specific needs. You may also want to include it in a larger MAKE file
  611.           #     which is used to generate your application. In any case, read carefully
  612.           #     the comments below and the "User's Guide", to understand what you can
  613.           #     change, and what should be used as is.
  614.           #  ------------------------------------------------------------------------------
  615.  
  616.           #
  617.           #  User provided name of the .DLL (to be filled)
  618.           #
  619.           USRNAME = ________
  620.  
  621.           STBNAME = zxxstub
  622.           INTNAME = zxxfuncs
  623.           RESNAME = zxxrsrcs
  624.  
  625.           #
  626.           #  Do not change OPTIONS unless really needed. They SHOULD match the original ones.
  627.           #
  628.           OPTIONS = /Kb /Ge- /Sm /Ss /Gd- /Gm+ /Ms /I-
  629.           LINKOPT = /NOI
  630.  
  631.           #
  632.           #  MAKE file generates a DLL and the corresponding IMPORT library having the
  633.           #  name specified as USRNAME above.
  634.           #
  635.           all: $(USRNAME).dll $(USRNAME).lib
  636.  
  637.           #
  638.           #  STUB should be compiled by using the same options used for Z Family/2 DLL
  639.           #
  640.           $(STBNAME).obj: $(STBNAME).c
  641.             icc /C+ $(OPTIONS) $(STBNAME).c
  642.  
  643.           #
  644.           #  Use STUB and Z Family/2 OBJECT library to generate the User's Cloned DLL
  645.           #  Use $(INTNAME).def to make your $(USRNAME).def, changing the name after
  646.           #  LIBRARY (first instruction of the definition file).
  647.           #
  648.           $(USRNAME).dll: $(STBNAME).obj $(INTNAME).lib $(USRNAME).def $(RESNAME).res
  649.            link386 $(LINKOPT) $(STBNAME).obj,$(USRNAME).dll,,$(INTNAME).lib,$(USRNAME).def ;
  650.            rc $(RESNAME).res $(USRNAME).dll
  651.  
  652.           #
  653.           #  Use the User's Cloned DLL to generate the corresponding IMPORT library
  654.           #
  655.           $(USRNAME).lib: $(USRNAME).dll $(USRNAME).def
  656.            implib $(USRNAME).lib $(USRNAME).def
  657.  
  658.   2. Edit ZCVFUNCS.DEF (see Skeleton of a definition to clone a Z Family/2 DLL) 
  659.      changing the name after LIBRARY  keyword to the desired name, that is, 
  660.      DLLCLONE. 
  661.  
  662.      Skeleton of a definition to clone a Z Family/2 DLL 
  663.  
  664.           ;
  665.           ; Module   : ZxxFUNCS.DEF
  666.           ; Authors  : Dario de Judicibus (DEJUDICI at ROMEPPC)
  667.           ;       Mario Turaccio (TURACCIO at ROMEPPC)
  668.           ; Reviewer  : Dario de Judicibus (DEJUDICI at ROMEPPC)
  669.           ; Created  : 21 Oct 1991
  670.           ; Updated  : 01 Apr 1993
  671.           ; Version  : 1.00
  672.           ; Content  : Module Definition File for FMZLXFUN.DLL
  673.           ; Product  : Z Family/2 Project (5641-504) FMZ
  674.           ;
  675.  
  676.           LIBRARY FMZxxFUN INITINSTANCE TERMINSTANCE
  677.           DESCRIPTION '... , Z Family/2 5641-504 (C) Copyright IBM Corporation 1993,1994.'
  678.  
  679.           PROTMODE
  680.           CODE  LOADONCALL
  681.           DATA  MULTIPLE READWRITE NONSHARED
  682.           HEAPSIZE  32768
  683.           STACKSIZE 32768
  684.  
  685.           IMPORTS
  686.                FMZyyFUN.zgsLibraryVersion
  687.                FMZyyFUN.zgsRegisterSignal
  688.                ...
  689.           EXPORTS
  690.                zxxLibraryVersion
  691.                zxxRegisterSignal
  692.                ...
  693.  
  694.   3. Generate the new DLL by executing: 
  695.  
  696.            NMAKE - af ZCVCLONE.MAK
  697.  
  698.  
  699. ΓòÉΓòÉΓòÉ 4.3.5. How to use the object library ΓòÉΓòÉΓòÉ
  700.  
  701. An object library called ZCVFUNCS.LIB is available in DEVEL sub-directory. 
  702.  
  703. Such a library is provided to allow the user to clone the FMZCVFUN.DLL library, 
  704. as explained in Create your own library. 
  705.  
  706.    Important 
  707.  
  708.    You may also decide to clone only few function rather than the whole 
  709.    library. However you cannot use this library to statically link some library 
  710.    function to your program. In fact, those functions which may need to load 
  711.    resources from the DLL itself, or to get the library handle to perform 
  712.    specific activities, wouldn't work any more. This use of the object library 
  713.    is not supported. You may do that, but at your own risk. 
  714.  
  715.  
  716. ΓòÉΓòÉΓòÉ 5. Reference Manual ΓòÉΓòÉΓòÉ
  717.  
  718. Select one: 
  719.  
  720.  Function sheets 
  721.  
  722.  Macro sheets 
  723.  
  724.  Data sheets 
  725.  
  726.  
  727. ΓòÉΓòÉΓòÉ 5.1. Function sheets ΓòÉΓòÉΓòÉ
  728.  
  729. Select one: 
  730.  
  731. Γûá zcvLibraryVersion
  732. Γûá zcvSetLibraryName
  733. Γûá zcvRegisterSignal
  734. Γûá zcvAllocTable
  735. Γûá zcvClearTable
  736. Γûá zcvConvertCharStream
  737. Γûá zcvConvertTextFile
  738. Γûá zcvCurrentCCSID
  739. Γûá zcvFreeTable
  740. Γûá zcvIsCCSIDSupported
  741. Γûá zcvMakeTable
  742. Γûá zcvQuerySupportedCCSIDs
  743.  
  744.  
  745. ΓòÉΓòÉΓòÉ 5.1.1. zcvLibraryVersion ΓòÉΓòÉΓòÉ
  746.  
  747. Provide information about library version and the date and time of compilation 
  748. of the DLL source code. 
  749.  
  750. Prototype 
  751.  
  752.  VOID EXPENTRY zcvLibraryVersion
  753.  (
  754.   zPLIBVERS pLibVers
  755.  ) ;
  756.  
  757. Parameters 
  758.  
  759.  pLibVers 
  760.       Pointer to a zLIBVERS structure. That structure should be allocated by 
  761.       the caller. Its content, if any, will be overwritten. 
  762.  
  763.  result 
  764.       The zLIBVERS structure whose pointer is provided as input parameter is 
  765.       filled. 
  766.  
  767.  Notes 
  768.  
  769.  Look at zLIBVERS for the definition of zLIBVERS structure. 
  770.  
  771.  Known bugs 
  772.  
  773.  None. 
  774.  
  775.  
  776. ΓòÉΓòÉΓòÉ 5.1.2. zcvSetLibraryName ΓòÉΓòÉΓòÉ
  777.  
  778. Set the value of the private variable zcvDllName. See also Create your own 
  779. library. 
  780.  
  781.    Important If called, this function must be called before any other library 
  782.    function. 
  783.  
  784.  Prototype 
  785.  
  786.    VOID EXPENTRY zcvSetLibraryName
  787.    (
  788.     PSZ szNewName
  789.    ) ;
  790.  
  791.  Parameters 
  792.  
  793.  szNewName 
  794.       Pointer to the string containing the new name of library. If you pass a 
  795.       NULL pointer or an empty string, the library name is set to its default, 
  796.       that is zcvDLLNAME. 
  797.  
  798.  result 
  799.       None. 
  800.  
  801.  Notes 
  802.  
  803.  If you clone FMZCVFUN.DLL, you obtain a new library with a new name. Since 
  804.  this library may need to know its name to load resources or get its module 
  805.  handle, you have to tell it which is the new name. You can use this function 
  806.  to do that. The default name is zcvDLLNAME. 
  807.  
  808.  Known bugs 
  809.  
  810.  None. 
  811.  
  812.  
  813. ΓòÉΓòÉΓòÉ 5.1.3. zcvRegisterSignal ΓòÉΓòÉΓòÉ
  814.  
  815. It registers an application signal handler for exception handling. 
  816.  
  817. Prototype 
  818.  
  819.  zSIGNAL EXPENTRY zcvRegisterSignal
  820.  (
  821.   zSIGHAND  SigHandler
  822.  )
  823.  
  824. Parameters 
  825.  
  826.  SigHandler 
  827.       Pointer to the application signal handler to be registered.  Type is 
  828.       zSIGHAND (see Z Family/2 general constants). 
  829.  
  830.  result 
  831.       zREGISTERED if the handler has been successfully registered, otherwise it 
  832.       returns the signal for which the registration failed.  See Signal 
  833.       handling types for the complete list of signals and their meaning. 
  834.  
  835.  Notes 
  836.  
  837.  Look at Signal handling  for a description of the exception handling feature 
  838.  provided by FMZCVFUN.DLL. 
  839.  
  840.  Known bugs 
  841.  
  842.  None. 
  843.  
  844.  
  845. ΓòÉΓòÉΓòÉ 5.1.4. zcvAllocTable ΓòÉΓòÉΓòÉ
  846.  
  847. Allocate an empty translation table that can be later filled by using 
  848. zcvMakeTable() or directly by the programmer. 
  849.  
  850. Prototype 
  851.  
  852.  BOOL EXPENTRY zcvAllocTable
  853.  (
  854.   zcvTABLE *ptable
  855.  )
  856.  
  857. Parameters 
  858.  
  859.  ptable 
  860.       Pointer to a variable of type zcvTABLE (see zcvTABLE) which will receive 
  861.       the pointer to the allocated table. In fact, note that zcvTABLE is a 
  862.       pointer too (see Tables for details). 
  863.  result 
  864.       If the empty table is allocated, the referenced variable is filled with 
  865.       its pointer, and TRUE is returned. If for any reason the function fails, 
  866.       it returns FALSE. 
  867.  
  868.  Notes 
  869.  
  870.  None. 
  871.  
  872.  Known bugs 
  873.  
  874.  Currently the table cannot be accessed by the C/C++ debugger IPMD. 
  875.  
  876.  
  877. ΓòÉΓòÉΓòÉ 5.1.5. zcvClearTable ΓòÉΓòÉΓòÉ
  878.  
  879. Clear a translation table, previously allocated by zcvAllocTable(), so that it 
  880. can be reused for another coded character set pair. 
  881.  
  882. Prototype 
  883.  
  884.  VOID EXPENTRY zcvClearTable
  885.  (
  886.   zcvTABLE table
  887.  )
  888.  
  889. Parameters 
  890.  
  891.  table 
  892.       The table to be cleared.  Its type is zcvTABLE (see zcvTABLE), which is 
  893.       really a pointer to a memory area (see Tables for details). 
  894.  result 
  895.       None. 
  896.  
  897.  Notes 
  898.  
  899.  None. 
  900.  
  901.  Known bugs 
  902.  
  903.  Currently the table cannot be accessed by the C/C++ debugger IPMD. 
  904.  
  905.  
  906. ΓòÉΓòÉΓòÉ 5.1.6. zcvConvertCharStream ΓòÉΓòÉΓòÉ
  907.  
  908. Convert a character stream according to the provided translation table. 
  909.  
  910. Prototype 
  911.  
  912.  BOOL EXPENTRY zcvConvertCharStream
  913.  (
  914.   zcvSTREAM instream  ,
  915.   zcvSTREAM outstream ,
  916.   ULONG   strsize  ,
  917.   zcvTABLE  table
  918.  )
  919.  
  920. Parameters 
  921.  
  922.  instream 
  923.       The character stream to be converted. It may contain any character in 
  924.       0x00 to 0xFF range, NULL included. 
  925.  outstream 
  926.       The character stream to be filled with the result of the translation. It 
  927.       may contain any character in 0x00 to 0xFF range, NULL included. 
  928.  strsize 
  929.       The size in bytes (or characters) of the input stream (the output stream 
  930.       will have the same size), or zcvNULLTERM if the character stream must be 
  931.       handled as a null-terminated string. 
  932.  table 
  933.       The translation table to be used for converting the input stream. 
  934.  result 
  935.       In the above mentioned former case, the function returns TRUE, in the 
  936.       latter case or if the function failed, it returns FALSE. 
  937.  
  938.  Notes 
  939.  
  940.  If strsize is zcvNULLTERM anyway, the character streams are handled as null 
  941.  terminated strings. In such a case the translation terminates at the first 
  942.  occurrence of a NULL character, and the output stream is null terminated too 
  943.  (i.e. the termination character is not involved in the translation). 
  944.  
  945.  It's a caller's responsibility to allocate the output buffer outstream. Note 
  946.  that zcvSTREAM is really a pointer to a buffer, which must be explicitely 
  947.  allocated. See Streams for details. 
  948.  
  949.  Known bugs 
  950.  
  951.  None. 
  952.  
  953.  
  954. ΓòÉΓòÉΓòÉ 5.1.7. zcvConvertTextFile ΓòÉΓòÉΓòÉ
  955.  
  956. Convert a text file according to the provided translation table. 
  957.  
  958. Prototype 
  959.  
  960.  BOOL EXPENTRY zcvConvertTextFile
  961.  (
  962.   PSZ    infile   ,
  963.   PSZ    outfile  ,
  964.   ULONG   behaviour ,
  965.   zcvTABLE  table
  966.  )
  967.  
  968. Parameters 
  969.  
  970.  infile 
  971.       The filename of the file to be converted, provided as in the standard C 
  972.       function fopen(). It may contain any character in 0x00 to 0xFF range, 
  973.       NULL, CSI and escape control sequences. included. 
  974.  outfile 
  975.       The filename of the output file, provided as in the standard C function 
  976.       fopen(). 
  977.  behaviour 
  978.       A flag indicating how the function should behave in relation to the 
  979.       existence of the output file. The following values are supported: 
  980.  
  981.     zcvCREATE           Create the output file if it doesn't exist (option A). 
  982.     zcvFAILIFNEW        Fail if the output file doesn't exist (option A). 
  983.     zcvREPLACE          Replace the output file if it already exist (option B). 
  984.     zcvAPPEND           Append to the output file if it already exist (option 
  985.                         B). 
  986.     zcvFAILIFEXISTS     Fail if the output file already exist (option B). 
  987.  
  988.       behaviour may consist of one of the two option A, or one of the three 
  989.       option B, or of the combination of an option A and and option B. In the 
  990.       first two cases, or if the flag is null, the following defaults apply: 
  991.  
  992.     o zcvCREATE 
  993.     o zcvREPLACE 
  994.  table 
  995.       The translation table to be used for converting the input file. 
  996.  result 
  997.       If the file is successfully converted, the function returns TRUE, 
  998.       otherwise it returns FALSE. 
  999.  
  1000.  Notes 
  1001.  
  1002.  None. 
  1003.  
  1004.  Known bugs 
  1005.  
  1006.  None. 
  1007.  
  1008.  
  1009. ΓòÉΓòÉΓòÉ 5.1.8. zcvCurrentCCSID ΓòÉΓòÉΓòÉ
  1010.  
  1011. Returns the first CCSID out of the list of those prepared for the machine where 
  1012. the program is running. 
  1013.  
  1014. Prototype 
  1015.  
  1016.  BOOL EXPENTRY zcvCurrentCCSID
  1017.  (
  1018.   zcvCCSID *pccsid
  1019.  )
  1020.  
  1021. Parameters 
  1022.  
  1023.  pccsid 
  1024.       The pointer to a variable of type zcvCCSID to be filled with the 
  1025.       requested codepage, if available, or zcvNOTPREPARED if none was prepared. 
  1026.  result 
  1027.       In the above mentioned former case, the function returns TRUE, in the 
  1028.       latter case or if the function failed, it returns FALSE. 
  1029.  
  1030.  Notes 
  1031.  
  1032.  None. 
  1033.  
  1034.  Known bugs 
  1035.  
  1036.  None. 
  1037.  
  1038.  
  1039. ΓòÉΓòÉΓòÉ 5.1.9. zcvFreeTable ΓòÉΓòÉΓòÉ
  1040.  
  1041. Free a translation table previously allocated by zcvAllocTable(), 
  1042.  
  1043. Prototype 
  1044.  
  1045.  BOOL EXPENTRY zcvFreeTable
  1046.  (
  1047.   zcvTABLE table
  1048.  )
  1049.  
  1050. Parameters 
  1051.  
  1052.  table 
  1053.       The table to be freed.  Its type is zcvTABLE (see zcvTABLE), which is 
  1054.       really a pointer to a memory area (see Tables for details). 
  1055.  result 
  1056.       If the empty table is freed, TRUE is returned.  If for any reason the 
  1057.       function fails, it returns FALSE. 
  1058.  
  1059.  Notes 
  1060.  
  1061.  None. 
  1062.  
  1063.  Known bugs 
  1064.  
  1065.  Currently the table cannot be accessed by the C/C++ debugger IPMD. 
  1066.  
  1067.  
  1068. ΓòÉΓòÉΓòÉ 5.1.10. zcvIsCCSIDSupported ΓòÉΓòÉΓòÉ
  1069.  
  1070. Check if the specified CCSID is supported by zcvMakeTable(). 
  1071.  
  1072. Prototype 
  1073.  
  1074.  BOOL EXPENTRY zcvIsCCSIDSupported
  1075.  (
  1076.   zcvCCSID ccsid
  1077.  )
  1078.  
  1079. Parameters 
  1080.  
  1081.  ccsid 
  1082.       The coded character set identifier to be checked against the list of 
  1083.       those supported by zcvMakeTable(). 
  1084.  result 
  1085.       TRUE if the CCSID is supported by zcvMakeTable(), otherwise FALSE . 
  1086.  
  1087.  Notes 
  1088.  
  1089.  None. 
  1090.  
  1091.  Known bugs 
  1092.  
  1093.  Supported CCSIDs are statically hardcoded in function, since there is no way, 
  1094.  at the moment, to obtain them dinamically from the system. This may cause a 
  1095.  bug if and when the list of the CCSIDs supported by ACSSVC.DLL will change in 
  1096.  future (see Supported CCSIDs for additional details). 
  1097.  
  1098.  
  1099. ΓòÉΓòÉΓòÉ 5.1.11. zcvMakeTable ΓòÉΓòÉΓòÉ
  1100.  
  1101. Built a translation table that was previously allocated by using 
  1102. zcvAllocTable(), from a supported coded character set to another. 
  1103.  
  1104. Prototype 
  1105.  
  1106.  BOOL EXPENTRY zcvMakeTable
  1107.  (
  1108.   zcvTABLE  table  ,
  1109.   zcvCCSID  sccsid ,
  1110.   zcvCCSID  tccsid
  1111.  )
  1112.  
  1113. Parameters 
  1114.  
  1115.  table 
  1116.       The table to be filled with the translation code points. See zcvTABLE for 
  1117.       details on zcvTABLE type. 
  1118.  sccsid 
  1119.       The coded character set of the source. It must be one of the CCSID 
  1120.       supported by ACSSVC function of ACSSVC.DLL. 
  1121.  tccsid 
  1122.       The coded character set of the target. It must be one of the CCSID 
  1123.       supported by ACSSVC function of ACSSVC.DLL. 
  1124.  result 
  1125.       If the table is filled, the function returns TRUE  is returned.  If for 
  1126.       any reason the function fails, it returns FALSE . 
  1127.  
  1128.  Notes 
  1129.  
  1130.  None. 
  1131.  
  1132.  Known bugs 
  1133.  
  1134.  Currently the table cannot be accessed by the C/C++ debugger IPMD. 
  1135.  
  1136.  
  1137. ΓòÉΓòÉΓòÉ 5.1.12. zcvQuerySupportedCCSIDs ΓòÉΓòÉΓòÉ
  1138.  
  1139. Return the list of all the CCSID's supported by zcvMakeTable(). 
  1140.  
  1141. Prototype 
  1142.  
  1143.  VOID EXPENTRY zcvQuerySupportedCCSIDs
  1144.  (
  1145.   zcvCCSID *pccsid
  1146.  )
  1147.  
  1148. Parameters 
  1149.  
  1150.  pccsid 
  1151.       The pointer to an array of elements of type zcvCCSID. to be filled with 
  1152.       all the CCSID's supported by zcvMakeTable(). 
  1153.  result 
  1154.       None. 
  1155.  
  1156.  Notes 
  1157.  
  1158.  The array must be allocated by the caller, and contain at least 64 elements. 
  1159.  The function won't check the array dimension, anyway. The list terminates when 
  1160.  a null CCSID is found (zcvENDOFLIST). 
  1161.  
  1162.  Known bugs 
  1163.  
  1164.  Supported CCSIDs are statically hardcoded in function, since there is no way, 
  1165.  at the moment, to obtain them dinamically from the system. This may cause a 
  1166.  bug if and when the list of the CCSIDs supported by ACSSVC.DLL will change in 
  1167.  future (see Supported CCSIDs for additional details). system. 
  1168.  
  1169.  
  1170. ΓòÉΓòÉΓòÉ 5.2. Macro sheets ΓòÉΓòÉΓòÉ
  1171.  
  1172. This library has no macros. 
  1173.  
  1174.  
  1175. ΓòÉΓòÉΓòÉ 5.3. Data sheets ΓòÉΓòÉΓòÉ
  1176.  
  1177. Select one: 
  1178.  
  1179. Γûá zLIBVERS
  1180. Γûá Signal handling types
  1181. Γûá zcvTABLE
  1182. Γûá zcvSTREAM
  1183. Γûá zcvCCSID
  1184. Γûá Library constants
  1185. Γûá Z Family/2 general constants
  1186.  
  1187.  
  1188. ΓòÉΓòÉΓòÉ 5.3.1. zLIBVERS ΓòÉΓòÉΓòÉ
  1189.  
  1190. This structure is used by all Z Family/2 DLL's to maintain information about 
  1191. the level of the library, and the date and time of compilation of library 
  1192. source code. 
  1193.  
  1194. Structure 
  1195.  
  1196.  typedef struct zLibVersion
  1197.  {
  1198.   USHORT Version       ;
  1199.   USHORT Release       ;
  1200.   USHORT Modification    ;
  1201.   CHAR  String[zLEVELSIZE] ;
  1202.   CHAR  Stamp[zSTAMPSIZE]  ;
  1203.   CHAR  Name[zNAMESIZE]   ;
  1204.  }
  1205.  zLIBVERS, *zPLIBVERS ;
  1206.  
  1207. Fields 
  1208.  
  1209.  Version 
  1210.       Library version.  Updated only when major functional changes are applied 
  1211.       to the library code. 
  1212.  
  1213.  Release 
  1214.       Library release.  Updated only when minor functional changes are applied 
  1215.       to the library code. 
  1216.  
  1217.  Modification 
  1218.       Library modification.  Updated when fixes are applied to the library 
  1219.       code. 
  1220.  
  1221.  String 
  1222.       A string containing the library level (version plus release). It must 
  1223.       match the values of version and release. 
  1224.  
  1225.  Stamp 
  1226.       A string containing the compilation time stamp. Usually the C Set/2 
  1227.       predefined constant __TIMESTAMP__ is assigned to this field. 
  1228.  
  1229.  Name 
  1230.       A string containing the library name. If the library was cloned with a 
  1231.       different name, and zcvSetLibraryName() was previously called, this 
  1232.       string contains the name of the clone. 
  1233.  
  1234.  Include file 
  1235.  
  1236.  zgeneral.h 
  1237.  
  1238.  Notes 
  1239.  
  1240.  This structure is the same for all the Z Family/2 DLL's. 
  1241.  
  1242.  
  1243. ΓòÉΓòÉΓòÉ 5.3.2. Signal handling types ΓòÉΓòÉΓòÉ
  1244.  
  1245. Two types are used in the signal handling feature of FMZCVFUN.DLL: zSIGHAND 
  1246. and zSIGNAL. 
  1247.  
  1248. zSIGHAND is the pointer to a signal handler function that can be used as 
  1249. argument when zcvRegisterSignal() is called (see Signal handling for details 
  1250. about how to write a signal handler). 
  1251.  
  1252. zSIGNAL  is the signal event that may be returned by zcvRegisterSignal() if the 
  1253. registration of the signal handler fails. 
  1254.  
  1255. Definition 
  1256.  
  1257.  typedef int  zSIGNAL      ;
  1258.  typedef void (*zSIGHAND)(int) ;
  1259.  
  1260. Signals 
  1261.  
  1262. This is the list of the possible values whose type is zSIGNAL. 
  1263.  
  1264.  SIGILL 
  1265.       Illegal instruction (invalid function image) 
  1266.  
  1267.  SIGSEGV 
  1268.       Invalid access to memory 
  1269.  
  1270.  SIGFPE 
  1271.       Floating point exception 
  1272.  
  1273.  SIGTERM 
  1274.       OS/2 SIGTERM (killprocess) signal 
  1275.  
  1276.  SIGABRT 
  1277.       Abort() signal 
  1278.  
  1279.  SIGINT 
  1280.       OS/2 SIGINTR signal 
  1281.  
  1282.  SIGUSR1 
  1283.       User exception in range 0xA0000000-0xBFFFFFFF 
  1284.  
  1285.  SIGUSR2 
  1286.       User exception in range 0xC0000000-0xDFFFFFFF 
  1287.  
  1288.  SIGUSR3 
  1289.       User exception in range 0xE0000000-0xFFFFFFFF 
  1290.  
  1291.  SIGBREAK 
  1292.       OS/2 Ctrl-Break sequence 
  1293.  
  1294.  Include file 
  1295.  
  1296.  zgeneral.h 
  1297.  
  1298.  Notes 
  1299.  
  1300.  These types are the same for all the Z Family/2 DLL's. 
  1301.  
  1302.  
  1303. ΓòÉΓòÉΓòÉ 5.3.3. zcvTABLE ΓòÉΓòÉΓòÉ
  1304.  
  1305. This type is defined as a pointer 16 to a memory area allocated within a 64K 
  1306. segment and alligned to a short word (2 bytes). 
  1307.  
  1308. Type 
  1309.  
  1310.  typedef  PCHAR16  zcvTABLE ;
  1311.  
  1312. Then, defining a variable of type zcvTABLE does not mean that the corresponding 
  1313. table has been defined. It is necessary to use zcvAllocTable() to properly 
  1314. allocate the table so that it can be filled by zcvMakeTable(). 
  1315.  
  1316. Include file 
  1317.  
  1318. zcvtypes.h 
  1319.  
  1320. Notes 
  1321.  
  1322. In order to use zcvTABLE type, it is necessary to compile your application by 
  1323. using the /DES32TO16 option, that is the ES32TO16 constant must be defined. 
  1324.  
  1325.  
  1326. ΓòÉΓòÉΓòÉ 5.3.4. zcvSTREAM ΓòÉΓòÉΓòÉ
  1327.  
  1328. This type is defined as the pointer to a buffer which contains a stream of 
  1329. characters or a null terminated string. 
  1330.  
  1331. Type 
  1332.  
  1333.  typedef  CHAR *zcvSTREAM ;
  1334.  
  1335. Include file 
  1336.  
  1337. zcvtypes.h 
  1338.  
  1339. Notes 
  1340.  
  1341. None 
  1342.  
  1343.  
  1344. ΓòÉΓòÉΓòÉ 5.3.5. zcvCCSID ΓòÉΓòÉΓòÉ
  1345.  
  1346. This type is defined as a long word which contains a coded character set 
  1347. identifier. 
  1348.  
  1349. Type 
  1350.  
  1351.  typedef  ULONG  zcvCCSID ;
  1352.  
  1353. Include file 
  1354.  
  1355. zcvtypes.h 
  1356.  
  1357. Notes 
  1358.  
  1359. None 
  1360.  
  1361.  
  1362. ΓòÉΓòÉΓòÉ 5.3.6. Library constants ΓòÉΓòÉΓòÉ
  1363.  
  1364. The following constants can be used by the applications that are dynamically 
  1365. linked to FMZCVFUN.DLL. 
  1366.  
  1367.  zcvDLLNAME 
  1368.       The default name of this library. Note that, if you clone this library, 
  1369.       the real name must be changed by using the zcvSetLibraryName() function. 
  1370.       In such a case, you cannot use any more this constant. 
  1371.  
  1372.  zcvZPREFIX 
  1373.       The Z Family/2 identifier of this library. 
  1374.  
  1375.  zcvNULLTERM 
  1376.       Used as the size of a character stream when zcvConvertCharStream() to 
  1377.       signal that the stream is really a null terminated string. 
  1378.  
  1379.  zcvNOTPREPARED 
  1380.       Returned by zcvCurrentCCSID() if no codepage has been prepared when the 
  1381.       function is called. 
  1382.  
  1383.  zcvENDOFLIST 
  1384.       Indicates that there are no more CCSID's in the list returned by 
  1385.       zcvQuerySupportedCCSIDs(). 
  1386.  
  1387.  zcvCREATE 
  1388.       Flag used to define the behaviour of zcvConvertTextFile() if the file 
  1389.       doesn't exist: create the file (default). 
  1390.  
  1391.  zcvFAILIFNEW 
  1392.       Flag used to define the behaviour of zcvConvertTextFile() if the file 
  1393.       doesn't exist: fail if file doesn't exist. 
  1394.  
  1395.  zcvREPLACE 
  1396.       Flag used to define the behaviour of zcvConvertTextFile() if the file 
  1397.       already exist: replace an existing file (default). 
  1398.  
  1399.  zcvAPPEND 
  1400.       Flag used to define the behaviour of zcvConvertTextFile() if the file 
  1401.       already exist: append to an existing file. 
  1402.  
  1403.  zcvFAILIFEXISTS 
  1404.       Flag used to define the behaviour of zcvConvertTextFile() if the file 
  1405.       already exist: fail if file exists. 
  1406.  
  1407.  Include file 
  1408.  
  1409.  zcvdefs.h 
  1410.  
  1411.  Notes 
  1412.  
  1413.  None. 
  1414.  
  1415.  
  1416. ΓòÉΓòÉΓòÉ 5.3.7. Z Family/2 general constants ΓòÉΓòÉΓòÉ
  1417.  
  1418. The following constants are shared by all Z Family/2 DLL's. 
  1419.  
  1420.  zPRODPREF 
  1421.       Z Family/2 three-character product prefix (ZCV). 
  1422.  
  1423.  zPRODNUMB 
  1424.       Z Family/2 product number (5641-504). 
  1425.  
  1426.  zCOPYRIGHT 
  1427.       Z Family/2 copyright statement. 
  1428.  
  1429.  zNAMESIZE 
  1430.       Maximum size of Name string in zLIBVERS. 
  1431.  
  1432.  zLEVELSIZE 
  1433.       Maximum size of Level string in zLIBVERS. 
  1434.  
  1435.  zSTAMPSIZE 
  1436.       Maximum size of Stamp string in zLIBVERS. 
  1437.  
  1438.  zNULLERRORID 
  1439.       Null error identifier. To be used when the error identifier can be 
  1440.       ignored by the called function. 
  1441.  
  1442.  zEXEMINERRID 
  1443.       Minimum value of error identifiers for user applications. 
  1444.  
  1445.  zEXEMAXERRID 
  1446.       Maximum value of error identifiers for user applications. 
  1447.  
  1448.  zDLLMINERRID 
  1449.       Minimum value of error identifiers for the Z Family/2 DLL's. 
  1450.  
  1451.  zDLLMAXERRID 
  1452.       Maximum value of error identifiers for the Z Family/2 DLL's. 
  1453.  
  1454.  zSIGNAL 
  1455.       Z Family/2 signal type for signal handling. 
  1456.  
  1457.  zSIGHAND 
  1458.       Z Family/2 signal handler type for signal handling. 
  1459.  
  1460.  zBIT 
  1461.       Z Family/2 type used for unsigned bits. 
  1462.  
  1463.  Include file 
  1464.  
  1465.  zgeneral.h 
  1466.  
  1467.  Notes 
  1468.  
  1469.  Error identifiers are used to identify both the error itself, and the message 
  1470.  associated with it. 
  1471.  
  1472.  
  1473. ΓòÉΓòÉΓòÉ 6. Sample Program ΓòÉΓòÉΓòÉ
  1474.  
  1475. Select one: 
  1476.  
  1477.  Running the sample program 
  1478.  
  1479.  Sample program tutorial 
  1480.  
  1481.  
  1482. ΓòÉΓòÉΓòÉ 6.1. Running the sample program ΓòÉΓòÉΓòÉ
  1483.  
  1484.  Important 
  1485.  
  1486.  To run the sample program, you must already have installed the library as 
  1487.  described in How to install the library. 
  1488.  
  1489.  Do not double-click on the item below unless 
  1490.  
  1491.   1. you copied the sample program to a directory listed in your PATH, or added 
  1492.      the directory where the sample program is to your PATH. 
  1493.  
  1494.   2. you copied all the needed dynamic libraries to a directory listed in your 
  1495.      LIBPATH, or added the directory where such libraries are to your LIBPATH. 
  1496.  
  1497.    Hit me to run the sample 
  1498.  
  1499.  
  1500. ΓòÉΓòÉΓòÉ 6.2. Sample program tutorial ΓòÉΓòÉΓòÉ
  1501.  
  1502. The FMZCVFUN.DLL package also contains a sample program that shows how to use 
  1503. the DLL functions. 
  1504.  
  1505. The program is called CVTEST  and can be launched either from an OS/2 window 
  1506. (or full-screen), or from the OS/2 Desktop, double-clicking on its icon. 
  1507.  
  1508. When the program is executed, a small windows appear on the screen. 
  1509.  
  1510. CVTEST window has only a single pull-down menu, called Translate. If you open 
  1511. that menu you can see four items: 
  1512.  
  1513.    Strings... 
  1514.         A dialog box is displayed. Its title is Translate String. The dialog is 
  1515.         divided in two similar sections. 
  1516.  
  1517.         The left side is used to enter the source string to be converted.  It 
  1518.         also contains a read-only entry field for the source coded character 
  1519.         set identifier (CCSID). In fact, you cannot select the CCSID of that 
  1520.         string, since you cannot in any case enter a string by using a CCSID 
  1521.         different from the current one prepared on your machine. 
  1522.  
  1523.         The right side allows you to select the target CCSID by using a drop 
  1524.         down list. As you press the Translate button which is placed in the 
  1525.         lower part of the dialog, just in the middle, the string is converted 
  1526.         and the result is shown in the right side of the dialog. 
  1527.  
  1528.         You may change the target CCSID and test the conversion of the same 
  1529.         input string several times. When you have finished, press the OK button 
  1530.         to close the dialog. Of course, if the conversion fails for any reason, 
  1531.         an appropriate error message is displayed. 
  1532.    Files... 
  1533.         A dialog box is displayed. Its title is Translate File. The dialog is 
  1534.         divided in two similar sections. 
  1535.  
  1536.         The left side is used to enter the name of the source file to be 
  1537.         converted.  It also contains a drop down list to select the source 
  1538.         coded character set identifier (CCSID). If you don't remember the name 
  1539.         of the source file, just press the Select source button below the entry 
  1540.         field, to get the File Requester. 
  1541.  
  1542.         The right side allows you to select the target CCSID by using a drop 
  1543.         down list, and specify the name of the output file. You may select an 
  1544.         already existent file by using the Select target button below the entry 
  1545.         field, as for the source file.  As you press the Translate button which 
  1546.         is placed in the lower part of the dialog, just in the middle, the file 
  1547.         is converted and a message is displayed. 
  1548.  
  1549.         You may change the target CCSID and test the conversion of the same 
  1550.         input file several times. When you have finished, press the 
  1551.    OK button to close the dialog. 
  1552.  
  1553.    Of course, if the conversion fails for any reason, an appropriate error 
  1554.    message is displayed. 
  1555.    About 
  1556.         A message box containing the name of the library, its version, the 
  1557.         author and some other related information (eg. copyright) is displayed. 
  1558.         The first two fields are obtained by the zcvLibraryVersion() function. 
  1559.    Exit 
  1560.         The user is prompted for the confirmation of the EXIT request. 
  1561.  
  1562.         Program ends. 
  1563.