═══ 1. Document Content ═══ This document is made up of five parts: Library Card General information card for this library. Installation Guide How to install the Z Family/2 reusable library and how to use the installed files. User's Guide How to integrate the library with your application and how to call the corresponding functions and macros. Reference Manual Reference information for the functions, macros and structures provided by this library. Sample Program How to call and use the sample program. ═══ 2. Library card ═══ ═══ Dummy ═══ Package: ZISFUNCS Library: FMZISFUN.DLL Version: 3.20 Requirements: OS/2 2.x, C Set/2 or IBM C/C++ Tools 2.0, Toolkit 2.x. Trademarks ═══ Dummy ═══ ═══ Dummy ═══ Contact: Dr. Dario de Judicibus IBMMAIL: ITIBM98W Internet: ddj@vnet.ibm.com ═══ 3. Installation Guide ═══ Select one: Library installation The expanded tree ═══ 3.1. Library installation ═══ Select one: ■ Package content ■ How to install the library ═══ 3.1.1. Package content ═══ FMZISFUN.DLL is distributed as a package containing the following files: ZISFUNCS.ZIP A ZIP compressed file which contains the library modules. ZISFUNCS.INF The on-line documentation for this reusable library. ═══ 3.1.2. How to install the library ═══ To install the libraries, you have to perform the following steps: 1. Locate the directory of the CD-ROM, remote partition, or diskette where ZISFUNCS.ZIP is placed. Let's say, for example, P:\ZFAMILY. 2. Move to the directory on your system where you want to install the reusable library. For example, move to D:\REUSE. 3. Unpack the ZIP file by using option -d. Please, note that such option must be lower case. In our case, issue the following command: [D:\REUSE] PKUNZIP2 -d P:\ZFAMILY\ZISFUNCS.ZIP 4. When the command is terminated, a new directory is available on your system. In our example, P:\ZFAMILY\ZIS. Such a directory contains several other sub-directories which contains all the files needed to use the reusable library. The directory tree is described in Library Tree. The content of each directory is described in detail in Content of directories. 5. In order to use the library, you must now move the unpacked files to the appropriate directories in your development environment. In particular move o the headers from .\ZIS\H to any directory listed in your INCLUDE environment variable. o the import and/or object libraries from .\ZIS\LIB and .\ZIS\DEVEL to any directory listed in your LIB environment variable. o the dynamic link libraries from .\ZIS\DLL to any directory listed in your LIBPATH environment variable. You may also want to move this file from .\ZIS\HELP to any directory listed in your BOOKSHELF environment variable. Now you are ready to work with the ZIS reusable library. ═══ 3.2. The expanded tree ═══ Select one: ■ Library tree ■ Content of directories ═══ 3.2.1. Library tree ═══ When you unpack ZISFUNCS.ZIP, a new sub-directory is created on your system: ZIS. Its structure is the following: current dir │ │ ZIS ├─┐ │ ├──── H . ├──── DLL . ├──── LIB . ├──── MRI . ├──── HELP . ├──── DEVEL . └──── SAMPLE ═══ 3.2.2. Content of directories ═══ Hereinafter is the list of the directories that are created when ZISFUNCS.ZIP is unpacked as described in How to install the library. The content of each directory is described in detail. The H sub-directory contains all the header files (H and RCH) to be added to the INCLUDE path of the application development environment. Move all the files from this directory to the appropriate path in your environment. Important If you use other Z Family/2 reusable libraries in your development environment, ensure that you are using the latest version of the zgeneral.h header file, which is available in all the library packages. You may do that by comparing the update dates in the prologue of the header file. /* ** Module : ZGENERAL.H ** Authors : Dario de Judicibus (DEJUDICI at ROMEPPC) ** Alessandro Cavallini (CAVALLI at ROMEPPC) ** Giacomo Lenoci ** Created : 10 Jan 1992 ** Updated : 01 Feb 1993 ** Version : 2.30 ** Content : General includes for all Z Family/2 DLLs ** Product : Z Family/2 Project (5641-504) FMZ ** */ The DLL sub-directory contains all the dynamic link library or libraries (DLL) to be added to the LIBPATH path of the application development environment and of the run environment. Move all the files from this directory to the appropriate path in your environment. The LIB sub-directory contains all the import library or libraries (LIB) to be added to the LIB path of the application development environment. Move all the files from this directory to the appropriate path in your environment. The MRI sub-directory contains all the translatable objects, that is texts that might be translated to other languages (see Machine Readable Information for additional information). The HELP sub-directory contains the documentation of libraries, and a news file (ZISNEWS.DOC) containing modifications applied at the last minute and not available in the on-line manuals, and the history of changes. The DEVEL sub-directory contains the object library or libraries (LIB) and the sample of the DEF and MAK files that can be used to generate your own DLL(s) (see Create your own library for details). The SAMPLE sub-directory contains the source code and the executable code of the sample program. It doesn't contain the DLL file(s) too, anyway. So, to run the sample, you must ensure that all the required DLL files have been copied to any directory of your LIBPATH. Such files are not only those pertaining to this library, but also those belonging on any pre-requisite Z Family/2 Reusable Library. Important If the library depends on other Z Family/2 reusable libraries, all the files belonging to the pre-requisite libraries will be part of the dependent library only in the beta versions of the package. The final version won't contain any pre-requisite file. That is true for the SAMPLE sub-directory too. So, you won't be able to recompile the sample program unless you install the pre-requisite packages too. ═══ 4. User's Guide ═══ Select one: General information Basic topics Advanced topics ═══ 4.1. General information ═══ Select one: ■ Library overview ■ Include files ■ Requirements ■ Development rules ■ Trademarks ═══ 4.1.1. Library overview ═══ This DLL contains a set of functions to verify if a certain object belongs or not to a specific class. They should be considered as an extension of ANSI C is-macros. In the current version most of functions can be used to check if a character string represents a certain type of number according to a specific notation. FMZISFUN.DLL is NLS enabled, that is recognizes the current settings for the decimal and thousand separators. For details see ■ Library Purpose ■ Definitions and notations ■ Algebra ═══ 4.1.2. Include files ═══ The system include files that are requested to use this library are: #define INCL_PM #define INCL_DOS #include #include #include #include #include #include The specific include files that are requested to use this library are: zgeneral.h Definitions and types for all Z Family/2 Reusable Libraries. zisdefs.h Macro and constants for this library. zistypes.h Type definitions for this library. zisproto.h Function prototypes for this library. Note: The specific includes must be included in the order as listed above. ═══ 4.1.3. Requirements ═══ FMZISFUN.DLL is intended to run under OS/2 2.x. It doesn't run under previous versions of OS/2. FMZISFUN.DLL has been compiled by IBM C/C++ Tools 2.0 and statically linked to the C run-time libraries. Then you don't need such libraries to use it. Notes FMZISFUN.DLL functions can be called either from C and from C++. In addition, an exception handler is registered for each exported function. This version of DLL is NLS enabled since it uses DosQueryCtryInfo() to obtain the current settings for the thousand and the decimal separators. A sample program that shows how to use FMZISFUN.DLL functions is provided in the DLL's package too. A short description of that sample is available in Sample program tutorial. The sample program uses the IMPORTS statement in its .DEF to import the FMZISFUN.DLL functions. File FMZISFUN.LIB is provided too as an alternative to such solution. It is also possible to create a clone of FMZISFUN.DLL by using the files available in the DEVEL sub-directory of the tree created by exploding the ZIP file distributed with the package (see Create your own library). ═══ 4.1.4. Development rules ═══ To safely integrate any Z Family/2 reusable library in your application, you need to follow a simple set of rules: 1. Do not use names beginning by a lower case "z" for o functions o macros o global structures o types o constants o #define o global variables 2. Do not use names beginning by a "z" for o include files (.H) o dynamic link libraries (.DLL) Follow these rules and your code can take full advantage of the services provided by the current and future Z Family Reusable Libraries/2. ═══ 4.1.5. Trademarks ═══ IBM Z Family/2 Reusable Libraries is copyrighted by IBM Corporation. IBM Corporation trademarks CUA Common User Access IBM IBM C Set/2 IBM C/C++ Tools Operating System/2 OS/2 Presentation Manager SAA Systems Application Architecture Workplace Shell Other trademarks Intel is a trademark of the Intel Corporation. Microsoft and Windows are trademarks of the Microsoft Corporation. PKZIP and PKUNZIP are trademarks of the PKWare Corporation. 80386 is a trademark of the Intel Corporation. ═══ 4.2. Basic topics ═══ Select one: ■ Library Purpose ■ Definitions and notations ■ Algebra ═══ 4.2.1. Library purpose ═══ FMZISFUN.DLL extends the services provided by the built-in C macros isxxxxx(), hereinafter called is-macros. That is, it allows to check if a certain string, integer, real, or in general any value satisfies certain requirements. Currently two different set of services are supported: o checking for strings representing numbers o checking for integers belonging to a specific range of values Additional services will be available in future. This kind of services are useful to check, for instance, if a certain value loaded from an entry field of a user interface is a valid number according to a certain notation. Note: Library functions do not perform any string conversion, but check the matching between the string value and the specified requirements. ═══ 4.2.2. Definitions and notations ═══ The following definitions are used in this document. Flat notation Just digits, without thousands separators. Decimal separator is accepted for reals only. Thousand notation Like the flat notation, but thousands separators are required. In case of reals, thousands separator must be used for both the integer and decimal part. Scientific notation It applies to real numbers only. Number is represented by a mantissa and exponent. The absolute value of the mantissa is always less than one. The exponent is separated from the mantissa by the character E or e. Exponential notation It applies to real numbers only. Number is represented by a mantissa and exponent. The absolute value of the mantissa can assume any value. The exponent is separated from the mantissa by the character E or e. Note: The characters representing the decimal separator and the thousands separator are not fixed, but retrieved from the system according to the current user settings. In fact, such characters are different in different countries, and can be customized by users. Typical decimal separators are commas (,) and dots (.). Typical thousands separators are commas (,), dots (.), single spaces (b) and stright single quotes ('). ═══ 4.2.3. Algebra ═══ Note that according to the algebra of the supported number types, naturals are a subset of integers, which in turn are a subset of reals. In addition, it is assumed that the subset of natural numbers does include zero. ═══ 4.3. Advanced topics ═══ Select one: ■ Machine Readable Information ■ Signal handling ■ Create your own library ■ How to generate the clone ■ How to use the object library ═══ 4.3.1. Machine Readable Information ═══ If the library contains translatable pieces of information, they are contained in resource files available in the MRI sub-directory of the ZIS directory, created at installation time (see Installation). To use such files, move all the header files in the H sub-directory to the appropriate path in your development environment, translate the resource files to the target language, recompile the file by using the command rc -r .RC to generate the corresponding RES file, and apply the result to the DLL file by using the command rc .RES .DLL Note that is not FMZISFUN but the name of the DLL cloned as described in Create your own library. ═══ 4.3.2. Signal handling ═══ FMZISFUN.DLL enables the handling of signals as follows. First, each exported function is preceeded in code by the corresponding pragma handler: Sample #pragma handler(zisLibraryVersion) VOID EXPENTRY zisLibraryVersion . . . Second, a standard function, available in any Z Family/2 reusable library, is provided to register a user's signal handler: zisRegisterSignal (see zisRegisterSignal). The user's signal handler is a function that accepts as input parameter an integer, and returns a void. A sample is shown hereinafter: Sample void UserSignalHandler (int signal) { switch (signal) { case SIGILL : /* Prepare to handle SIGILL */ break ; case SIGSEGV : /* Prepare to handle SIGSEGV */ break ; case SIGFPE : /* Prepare to handle SIGFPE */ break ; case SIGTERM : /* Prepare to handle SIGTERM */ break ; case SIGABRT : /* Prepare to handle SIGABRT */ break ; case SIGINT : /* Prepare to handle SIGINT */ break ; case SIGUSR1 : /* Prepare to handle SIGUSR1 */ break ; case SIGUSR2 : /* Prepare to handle SIGUSR2 */ break ; case SIGUSR3 : /* Prepare to handle SIGUSR3 */ break ; case SIGBREAK: /* Prepare to handle SIGBREAK */ break ; default : /* Unknown signal */ break ; } /* ** Handle the received signal according to the previous ** preparation. In general, show a message and terminate ** the program. */ } ═══ 4.3.3. Create your own library ═══ It is possible for the reuser to decide to clone a Z Family/2 reusable library with a different name. Since the source code is not available to reusers, it is possible to do that by using the files in the DEVEL sub-directory. Important Such files are not intended to be used as they are, but should be modified as described below. The DEVEL directory contains at least four files: ZISFUNCS.LIB An object library ZISFUNCS.DEF A skeleton for the definition file ZISCLONE.MAK A skeleton for the make file ZISSTUB.C A stub file used to generate the library In addition, it may also contain one or more resource files, that is ZISxxxxx.RES files. Important This library may need to load resources from itself, or to get its module handle. If you clone the library and change its name, it has no way to automatically know which is its new name. So you need to tell it about. You can do that by using the zisSetLibraryName() function. ═══ 4.3.4. How to generate the clone ═══ To generate a clone of FMZISFUN.DLL with a different name, you have to execute the following steps: 1. Edit ZISCLONE.MAK (see Skeleton of a makefile to clone a Z Family/2 DLL) changing USRNAME to the wanted name. Let's say, for example, DLLCLONE. You may want to add other instructions to this make file, but be careful if you want to change the existing ones In particular, the OPTIONS constant contains the same options used to compile FMZISFUN.DLL. If you change them, the new DLL may not work as expected. Skeleton of a makefile to clone a Z Family/2 DLL # # Module : ZxxCLONE.MAK # Authors : Luca Miccoli (MICCOLI at ROMEPPC) # Reviewer : Dario de Judicibus (DEJUDICI at ROMEPPC) # Created : 06 Apr 1993 # Reviewed : 21 Apr 1993 # Version : 1.00 # Content : Make File for Z Family/2 Clones # # ------------------------------------------------------------------------------ # # NOTE : This is a SAMPLE makefile. You may need to modify it to satisfy your # specific needs. You may also want to include it in a larger MAKE file # which is used to generate your application. In any case, read carefully # the comments below and the "User's Guide", to understand what you can # change, and what should be used as is. # ------------------------------------------------------------------------------ # # User provided name of the .DLL (to be filled) # USRNAME = ________ STBNAME = zxxstub INTNAME = zxxfuncs RESNAME = zxxrsrcs # # Do not change OPTIONS unless really needed. They SHOULD match the original ones. # OPTIONS = /Kb /Ge- /Sm /Ss /Gd- /Gm+ /Ms /I- LINKOPT = /NOI # # MAKE file generates a DLL and the corresponding IMPORT library having the # name specified as USRNAME above. # all: $(USRNAME).dll $(USRNAME).lib # # STUB should be compiled by using the same options used for Z Family/2 DLL # $(STBNAME).obj: $(STBNAME).c icc /C+ $(OPTIONS) $(STBNAME).c # # Use STUB and Z Family/2 OBJECT library to generate the User's Cloned DLL # Use $(INTNAME).def to make your $(USRNAME).def, changing the name after # LIBRARY (first instruction of the definition file). # $(USRNAME).dll: $(STBNAME).obj $(INTNAME).lib $(USRNAME).def $(RESNAME).res link386 $(LINKOPT) $(STBNAME).obj,$(USRNAME).dll,,$(INTNAME).lib,$(USRNAME).def ; rc $(RESNAME).res $(USRNAME).dll # # Use the User's Cloned DLL to generate the corresponding IMPORT library # $(USRNAME).lib: $(USRNAME).dll $(USRNAME).def implib $(USRNAME).lib $(USRNAME).def 2. Edit ZISFUNCS.DEF (see Skeleton of a definition to clone a Z Family/2 DLL) changing the name after LIBRARY keyword to the wanted name, that is, DLLCLONE. Skeleton of a definition to clone a Z Family/2 DLL ; ; Module : ZxxFUNCS.DEF ; Authors : Dario de Judicibus (DEJUDICI at ROMEPPC) ; Mario Turaccio (TURACCIO at ROMEPPC) ; Reviewer : Dario de Judicibus (DEJUDICI at ROMEPPC) ; Created : 21 Oct 1991 ; Updated : 01 Apr 1993 ; Version : 1.00 ; Content : Module Definition File for FMZLXFUN.DLL ; Product : Z Family/2 Project (5641-504) FMZ ; LIBRARY FMZxxFUN INITINSTANCE TERMINSTANCE DESCRIPTION '... , Z Family/2 5641-504 (C) Copyright IBM Corporation 1993,1994.' PROTMODE CODE LOADONCALL DATA MULTIPLE READWRITE NONSHARED HEAPSIZE 32768 STACKSIZE 32768 IMPORTS FMZyyFUN.zgsLibraryVersion FMZyyFUN.zgsRegisterSignal ... EXPORTS zxxLibraryVersion zxxRegisterSignal ... 3. Generate the new DLL by executing: NMAKE - af ZISCLONE.MAK ═══ 4.3.5. How to use the object library ═══ An object library called ZISFUNCS.LIB is available in DEVEL sub-directory. Such a library is provided to allow the user to clone the FMZISFUN.DLL library, as explained in Create your own library. Important You may also decide to clone only few function rather than the whole library. However you cannot use this library to statically link some library function to your program. In fact, those functions which may need to load resources from the DLL itself, or to get the library handle to perform specific activities, wouldn't work any more. This use of the object library is not supported. You may do that, but at your own risk. ═══ 5. Reference Manual ═══ Select one: Function sheets Macro sheets Data sheets ═══ 5.1. Function sheets ═══ Select one: ■ zisLibraryVersion ■ zisSetLibraryName ■ zisRegisterSignal ■ zisAnyIntString ■ zisAnyNatString ■ zisAnyRealString ■ zisExpRealString ■ zisInIntRange ■ zisIntString ■ zisNatString ■ zisRealString ■ zisSciRealString ■ zisThsIntString ■ zisThsNatString ■ zisThsRealString ═══ 5.1.1. zisLibraryVersion ═══ Provide information about library version and the date and time of compilation of the DLL source code. Prototype VOID EXPENTRY zisLibraryVersion ( zPLIBVERS pLibVers ) ; Parameters pLibVers Pointer to a zLIBVERS structure. That structure should be allocated by the caller. Its content, if any, will be overwritten. result The zLIBVERS structure whose pointer is provided as input parameter is filled. Notes Look at zLIBVERS for the definition of zLIBVERS structure. Known bugs None. ═══ 5.1.2. zisSetLibraryName ═══ Set the value of the private variable zisDllName. See also Create your own library. Important If called, this function must be called before any other library function. Prototype VOID EXPENTRY zisSetLibraryName ( PSZ szNewName ) ; Parameters szNewName Pointer to the string containing the new name of library. If you pass a NULL pointer or an empty string, the library name is set to its default, that is zisDLLNAME. result None. Notes If you clone FMZISFUN.DLL, you obtain a new library with a new name. Since this library may need to know its name to load resources or get its module handle, you have to tell it which is the new name. You can use this function to do that. The default name is zisDLLNAME. Known bugs None. ═══ 5.1.3. zisRegisterSignal ═══ It allows to register an application signal handler for exception handling. Prototype zSIGNAL EXPENTRY zisRegisterSignal ( zSIGHAND SigHandler ) Parameters SigHandler Pointer to the application signal handler to be registered. Type is zSIGHAND (see Z Family/2 general constants). result zREGISTERED if the handler has been successfully registered, otherwise it returns the signal for which the registration failed. See Signal handling types for the complete list of signals and their meaning. Notes Look at Signal handling for a description of the exception handling feature provided by FMZISFUN.DLL. Known bugs None. ═══ 5.1.4. zisAnyIntString ═══ Check if a string represents an integer in any notation (flat or thousand). Prototype BOOL EXPENTRY zisAnyIntString ( PSZ pszString ) ; Parameters psz Pointer to the string to be checked. result TRUE if the string represents a valid integer in flat or thousand notation, otherwise FALSE. Notes To have a valid representation at least one digit has to be supplied. Known bugs None ═══ 5.1.5. zisAnyNatString ═══ Check if a string represents a natural number in any notation (flat or thousand). Prototype BOOL EXPENTRY zisAnyNatString ( PSZ pszString ) ; Parameters psz Pointer to the string to be checked. result TRUE if the string represents a valid natural in flat or thousand notation, otherwise FALSE. Notes To have a valid representation at least one digit has to be supplied. Known bugs None. ═══ 5.1.6. zisAnyRealString ═══ Check if a string represents a real number in any notation (flat, thousand, scientific or exponential). Prototype BOOL EXPENTRY zisAnyRealString ( PSZ pszString ) ; Parameters psz Pointer to the string to be checked. result TRUE if the string represents a valid real in flat, thousand, scientific or exponential notation, otherwise FALSE . Notes To have a valid representation at least one digit has to be supplied. Note that scientific and exponential notations cannot contain thousand separators. Known bugs None ═══ 5.1.7. zisExpRealString ═══ Check if a string represents a real in exponential notation. Prototype BOOL EXPENTRY zisExpRealString ( PSZ pszString ) ; Parameters psz Pointer to the string to be checked. result TRUE if the string represents a valid real in exponential notation, otherwise FALSE. Notes The exponential notation is described in Definitions and notations. Any real number will be considered a valid value. So the decimal separator is optional too. If the exponent symbol is found at least one digit has to follow it. Known bugs None ═══ 5.1.8. zisInIntRange ═══ Check if an integer value is included between the specified boundaries. Prototype BOOL EXPENTRY zisInIntRange ( INT value , INT first , INT second ); Parameters value Value to be checked first First boundary of the range (not necessarly the lower value) second_limit Second boundary of the range (not necessarly the upper value) result TRUE if the string is inside the provided range, otherwise FALSE. Notes No assumption is made about the order of first and second. For example, zisInIntRange(12,4,15) is TRUE zisInIntRange(12,15,4) is TRUE zisInIntRange(12,3,10) is FALSE zisInIntRange(12,10,3) is FALSE Known bugs None ═══ 5.1.9. zisIntString ═══ Check if a string represents an integer in flat notation. Both signed and unsigned integers are accepted. Prototype BOOL EXPENTRY zisIntString ( PSZ pszString ) ; Parameters psz Pointer to the string to be checked result TRUE if the string represents a valid integer in flat notation, otherwise FALSE. Notes To have a valid representation at least one digit has to be supplied. Known bugs None ═══ 5.1.10. zisNatString ═══ Check if a string represents a Natural number in flat notation. Prototype BOOL EXPENTRY zisNatString ( PSZ pszString ) ; Parameters psz Pointer to the string to be checked. result TRUE if the string represents a valid natural in flat notation, otherwise FALSE. Notes To have a valid representation at least one digit has to be supplied. Known bugs None ═══ 5.1.11. zisRealString ═══ Check if a string represents a real in flat notation. Prototype BOOL EXPENTRY zisRealString ( PSZ pszString ) ; Parameters psz Pointer to the string to be checked. result TRUE if the string represents a valid real in flat notation, otherwise FALSE. Notes To have a valid representation at least one digit has to be supplied. The decimal separator is not required, that is a natural or an integer in flat notation is accepted too. Known bugs None ═══ 5.1.12. zisSciRealString ═══ Check if a string represents a real in scientific notation. Prototype BOOL EXPENTRY zisSciRealString ( PSZ pszString ) ; Parameters psz Pointer to the string to be checked. result TRUE if the string represents a valid real in scientific notation, otherwise FALSE. Notes The scientific notation is described in Definitions and notations. Since that notation requires that the first digit be a zero, any real number whose absolute value is less than one will be considered a valid value. Then the decimal separator is mandatory. The zero before the decimal separator may be omitted. If the exponent symbol is found at least one digit has to follow it. Known bugs None. ═══ 5.1.13. zisThsIntString ═══ Check if a string represents an integer in thousand notation. Both signed and unsigned integers are accepted. Prototype BOOL EXPENTRY zisThsIntString ( PSZ pszString ) ; Parameters psz Pointer to the string to be checked. result TRUE if the string represents a valid integer in thousand notation, otherwise FALSE. Notes To have a valid representation at least one digit has to be supplied. Known bugs None ═══ 5.1.14. zisThsNatString ═══ Check if a string represents a natural number in thousand notation. Prototype BOOL EXPENTRY zisThsNatString ( PSZ pszString ) ; Parameters psz Pointer to the string to be checked. result TRUE if the string represents a valid natural in thousand notation, otherwise FALSE. Notes To have a valid representation at least one digit has to be supplied. Known bugs None ═══ 5.1.15. zisThsRealString ═══ Check if a string represents a real in thousand notation. Prototype BOOL EXPENTRY zisThsRealString ( PSZ pszString ) ; Parameters psz Pointer to the string to be checked. result TRUE notation, otherwise FALSE. Notes To have a valid representation at least one digit has to be supplied. The decimal separator is not required, that is a natural or an integer in thousand notation is accepted too. Known bugs None ═══ 5.2. Macro sheets ═══ This library has no macros. ═══ 5.3. Data sheets ═══ Select one: ■ zLIBVERS ■ Signal handling types ■ Library constants ■ Z Family/2 general constants ═══ 5.3.1. zLIBVERS ═══ This structure is used by all Z Family/2 DLL's to maintain information about the level of the library, and the date and time of compilation of library source code. Structure typedef struct zLibVersion { USHORT Version ; USHORT Release ; USHORT Modification ; CHAR String[zLEVELSIZE] ; CHAR Stamp[zSTAMPSIZE] ; CHAR Name[zNAMESIZE] ; } zLIBVERS, *zPLIBVERS ; Fields Version Library version. Updated only when major functional changes are applied to the library code. Release Library release. Updated only when minor functional changes are applied to the library code. Modification Library modification. Updated when fixes are applied to the library code. String A string containing the library level (version plus release). It must match the values of version and release. Stamp A string containing the compilation time stamp. Usually the C Set/2 predefined constant __TIMESTAMP__ is assigned to this field. Name A string containing the library name. If the library was cloned with a different name, and zisSetLibraryName() was previously called, this string contains the name of the clone. Include file zgeneral.h Notes This structure is the same for all the Z Family/2 DLL's. ═══ 5.3.2. Signal handling types ═══ Two types are used in the signal handling feature of FMZISFUN.DLL: zSIGHAND and zSIGNAL. zSIGHAND is the pointer to a signal handler function that can be used as argument when ZISRegisterSignal() is called (see Signal handling for details about how to write a signal handler). zSIGNAL is the signal event that may be returned by zisRegisterSignal() if the registration of the signal handler fails. Definition typedef int zSIGNAL ; typedef void (*zSIGHAND)(int) ; Signals This is the list of the possible values whose type is zSIGNAL. SIGILL Illegal instruction (invalid function image) SIGSEGV Invalid access to memory SIGFPE Floating point exception SIGTERM OS/2 SIGTERM (killprocess) signal SIGABRT Abort() signal SIGINT OS/2 SIGINTR signal SIGUSR1 User exception in range 0xA0000000-0xBFFFFFFF SIGUSR2 User exception in range 0xC0000000-0xDFFFFFFF SIGUSR3 User exception in range 0xE0000000-0xFFFFFFFF SIGBREAK OS/2 Ctrl-Break sequence Include file zgeneral.h Notes These types are the same for all the Z Family/2 DLL's. ═══ 5.3.3. Library constants ═══ Hereinafter a list of all the constants that could be used by the applications that are dynamically linked to FMZISFUN.DLL is shown. zisDLLNAME The default name of this library. Note that, if you clone this library, the real name must be changed by using the zisSetLibraryName() function. In such a case, you cannot use any more this constant. zisZPREFIX The Z Family/2 identifier of this library. Include file zisdefs.h Notes None. ═══ 5.3.4. Z Family/2 general constants ═══ Hereinafter a list of all the constants shared by all Z Family/2 DLL's is shown. zPRODPREF Z Family/2 product three character prefix identifier (ZIS). zPRODNUMB Z Family/2 product number (5641-504). zCOPYRIGHT Z Family/2 copyright statement. zNAMESIZE Maximum size of Name string in zLIBVERS. zLEVELSIZE Maximum size of Level string in zLIBVERS. zSTAMPSIZE Maximum size of Stamp string in zLIBVERS. zNULLERRORID Null error identifier. To be used when the error identifier can be ignored by the called function. zEXEMINERRID Minimum value of error identifiers for user applications. zEXEMAXERRID Maximum value of error identifiers for user applications. zDLLMINERRID Minimum value of error identifiers for the Z Family/2 DLL's. zDLLMAXERRID Maximum value of error identifiers for the Z Family/2 DLL's. zSIGNAL Z Family/2 signal type for signal handling. zSIGHAND Z Family/2 signal handler type for signal handling. zBIT Z Family/2 type used for unsigned bits. Include file zgeneral.h Notes Error identifiers are used to identify both the error itself, and the message associated to it. ═══ 6. Sample Program ═══ Select one: Running the sample program Sample program tutorial ═══ 6.1. Running the sample program ═══ Important To run the sample program, you must already have installed the library as described in How to install the library. Do not double-click on the item below unless 1. you copied the sample program to a directory listed in your PATH, or added the directory where the sample program is to your PATH. 2. you copied all the needed dynamic libraries to a directory listed in your LIBPATH, or added the directory where such libraries are to your LIBPATH. Hit me to run the sample ═══ 6.2. Sample program tutorial ═══ The FMZISFUN.DLL package contains also a sample program that shows how to use the DLL functions. The program is called CHKFUN and can be launched either from an OS/2 window (or full-screen), or from the OS/2 Desktop, double-clicking on its icon. When the program is executed, a small windows appear on the screen. If you open that menu you can see three items: Start... A dialog box is displayed. Its title is Check numbers. Such a dialog allows you to select the type of number you wish to check and which notation should be used. As soon as you select such values, a corresponding sample is shown in the Sample field. Now you should simply enter any number in the Input value field and press ENTER or click on the Check value  button to see if the provided value corresponds to the type of number and notation previously selected. You may compare other values with the same selection by simply entering the new values, or you may make another selection by using the two drop down lists in the top half of the dialog box. To leave the dialog just click on the EXIT button. About A message box containing the name of the library, its version, the author and some other related information (eg. copyright) is displayed. The first two fields are obtained by the zisLibraryVersion() function. Exit The user is prompted for the confirmation of the EXIT request. Program ends. Note: Since FMZISFUN.DLL is NLS enabled, you should use the decimal and thousand separators corresponding to the current settings of your machine. The purpose of the sample field is that to show to you which are the current settings for such separators.